概述

本指南旨在帮助用户在 RedHat 系 Linux 服务器上，利用 Docker 技术部署 New-API 服务，聚合 ModelScope (魔搭) 与 NVIDIA NIM 等免费算力资源，最终通过 Cherry Studio 客户端构建一套功能完备的 AI 工作台。

架构概览

  • 基础设施: RedHat / CentOS / Fedora / Alibaba Cloud Linux / Rocky
  • 核心中间件: Docker 容器引擎
  • 服务网关: New-API（负责接口聚合、密钥管理与负载均衡）
  • 推理源: ModelScope API + NVIDIA NIM API（免费资源）
  • 交互终端: Cherry Studio（客户端应用）

第一部分：服务器环境准备

本节适用于 RedHat 系发行版，并建议使用海外的VPS，避免因为网络原因而无法拉取docker hub资源。请确保您拥有服务器的 root 权限或具有 sudo 权限的用户。

1. 卸载旧版本（可选）

为避免依赖冲突，建议先移除系统可能预装的旧版 Docker 组件。

sudo dnf remove docker \
    docker-client \
    docker-client-latest \
    docker-common \
    docker-latest \
    docker-latest-logrotate \
    docker-logrotate \
    docker-engine

2. 配置软件源

安装依赖工具并添加 Docker 官方仓库，以确保获取最新稳定版本。

# 安装 dnf 核心插件
sudo dnf -y install dnf-plugins-core

# 添加 Docker CE 官方仓库
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

3. 安装 Docker Engine

执行以下命令安装 Docker 及其相关组件。

sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

注意：安装过程中若提示 GPG 密钥验证，请确认指纹匹配后输入 y 继续。

4. 启动与自检

安装完成后，启动服务并验证运行状态。

# 启动 Docker 服务
sudo systemctl start docker

# 设置开机自启
sudo systemctl enable --now docker

# 运行测试容器
sudo docker run hello-world

若输出 "Hello from Docker!" 信息，表明环境部署成功。

5. 配置防火墙（关键步骤）

RedHat 系默认启用 firewalld，需放行端口以确保外部可访问后续部署的服务。

# 开放 3000 端口（New-API 默认端口）
sudo firewall-cmd --permanent --add-port=3000/tcp

# 重载防火墙规则
sudo firewall-cmd --reload

注：若使用云服务器（如阿里云、AWS），还需在云平台控制台的“安全组”中放行 TCP 3000 端口。

第二部分：部署 New-API 核心服务

New-API 作为中间层，负责统一管理不同大模型供应商的接口。

1. 拉取并启动容器

执行以下命令启动服务。命令已包含数据持久化配置，避免重启后数据丢失。

docker run --name new-api \
  -d \
  --restart always \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v /home/ubuntu/data/new-api:/data \
  calciumion/new-api:latest

参数说明：

  • -d: 后台运行容器。
  • --restart always: 容器异常退出或服务器重启时自动重启。
  • -p 3000:3000: 将宿主机 3000 端口映射到容器内部 3000 端口。
  • -v ...: 挂载数据卷，确保数据库和配置文件持久存储。

2. 初始化与安全设置

  1. 访问地址：http://<您的服务器公网IP>:3000
  2. 默认凭证：
    • 账号：root
    • 密码：123456
  3. 安全警告：登录后请立即前往 “个人设置” 修改默认密码，防止未授权访问。

第三部分：配置免费模型渠道

在 New-API 管理后台，点击左侧菜单 “渠道” -> “添加新的渠道”，按以下指引添加免费推理源。

渠道 A：魔搭社区

渠道 B：英伟达 (NVIDIA NIM)

提示：添加完成后，建议在“渠道”列表中点击“测试”按钮，确认连通性正常。

第四部分：生成客户端访问令牌

New-API 不直接使用供应商密钥与客户端交互，需生成统一的访问令牌。

  1. 点击左侧 “令牌” -> “添加新的令牌”。
  2. 配置建议：
    • 名称：CherryClient
    • 过期时间：永不过期
    • 额度：无限额度
  3. 提交后，点击 “复制” 按钮保存生成的 sk- 开头的密钥。

第五部分：配置 Cherry Studio 客户端

1. 获取客户端

访问 Cherry Studio 官网 或 GitHub 下载对应操作系统的客户端。

2. 配置模型服务商

  1. 打开客户端，点击左下角 “设置” (齿轮图标)。
  2. 选择 “模型服务” -> 找到 “New API” (或添加“自定义服务商”)。
  3. 填写连接信息：
    • API 域名：http://<您的服务器公网IP>:3000/v1
      • 重点：必须以 /v1 结尾，这是 OpenAI 协议的标准路径。
    • API 密钥：粘贴第四部分生成的 sk- 密钥。
  4. 点击 “检查”，若显示连接成功，则配置无误。

3. 模型调用

  1. 在设置页面的 “模型列表” 中，点击 “管理”。
  2. 选择需要添加的模型，并点击红框标注的位置添加。
  3. 返回对话界面，在顶部下拉菜单选择刚添加的模型，即可开始对话。

故障排除

问题现象 诊断与解决方案
客户端提示连接超时 1. 检查服务器防火墙是否放行 3000 端口。
2. 检查云服务商安全组规则是否放行入站流量。
3. 确认 Docker 容器状态为 Up (docker ps)。
客户端提示 404 Not Found 检查 API 域名是否包含 /v1 后缀。正确的格式为 http://IP:PORT/v1。
NVIDIA 模型返回错误 NVIDIA 模型 ID 区分大小写且需包含命名空间（如 meta/）。请严格对照 NVIDIA NIM 官网 的模型名称填写。
Docker 端口冲突 若 3000 端口被占用，修改启动命令为 -p 3001:3000，并同步修改防火墙和安全组规则。