admin/test

0 Fork 0

Files

T

2026-11-05 14:10:48 +08:00

14 KiB

Raw Blame History

New API 专属大模型网关搭建与 HTTPS 上线全流程实战指南

实战环境记录

云服务器：腾讯云新加坡轻量应用服务器（Ubuntu 24.04 LTS，2核 2G 内存，公网 IP：43.156.118.130）

共存服务：Xray Shadowsocks 代理服务（端口 8388，全程独立运行，互不干扰）

域名提供商：Spaceship（根域名：trivoo.website，网关二级子域名：api.trivoo.website）

网关核心：New API（官方镜像 calciumion/new-api:latest，Docker 容器化 + 内置 SQLite 持久化）

反代与加密：Nginx 反向代理 + Let's Encrypt 权威 SSL 证书（Certbot 自动化定时续期）

一、全局架构与准备工作
二、第一阶段：域名注册与 DNS 解析配置
三、第二阶段：云服务器防火墙安全配置
四、第三阶段：New API 容器化部署
五、第四阶段：Nginx 反向代理与 SSL 证书自动化
六、第五阶段：New API 初始化与渠道配置
七、第六阶段：客户端接入与高频踩坑排错手册
八、第七阶段：日常运维、安全加固与一键清理

一、全局架构与准备工作

本方案采用**“单容器 SQLite + Nginx 本地反代 + Certbot 自动化证书”**的生产级架构：

[ 客户端 (Cline / Cherry Studio / 代码) ]
                  │  HTTPS (端口 443)
                  ▼
[ Nginx 反向代理 (api.trivoo.website) ] ── (自动申请/更新 Let's Encrypt 证书)
                  │  HTTP (仅监听 127.0.0.1:3000，外部无法直连)
                  ▼
[ New API 容器 (calciumion/new-api:latest) ]
                  │
        ┌─────────┴─────────┐
        ▼                   ▼
[ 官方 DeepSeek API ]   [ 自定义第三方聚合上游 ]

核心设计优势：

轻量省资源：相比 PostgreSQL + Redis 的重型部署，内置 SQLite 单容器仅占几十兆内存，完美兼容 2G 内存低配服务器，与已有代理服务（如 Xray）和谐共存。
端口安全性：New API 容器端口严格绑定在 127.0.0.1:3000，外部网络无法绕过 HTTPS 直接访问，防止明文直连与未授权嗅探。
流式传输优化：Nginx 明确关闭 proxy_buffering，保障大模型打字机流式输出（SSE）流畅无卡顿。

二、第一阶段：域名注册与 DNS 解析配置

1. 域名选购（以 Spaceship 为例）

访问 Spaceship 官网并注册/登录账号；
搜索低成本优质后缀（如 .website、.top、.xyz 等，首年特价通常仅约 6~10 元人民币）；
选定域名（本次实战选定 trivoo.website，首年仅 7.88 元含 ICANN 认证工本费）；
通过绑定的 支付宝（Alipay） 扫码付款完成购买。
重要防扣费设置：购买完成后，在域名列表的 Auto-renew 列将开关拨至 Off，避免次年按原价自动续费。

2. 添加 DNS A 记录解析

在 Spaceship 控制台点击域名右侧的 Advanced DNS ↗；
点击 Add Record（或点击下方小圆圈 A）：
- Type：A
- Host：api（即二级子域名，完整网址为 api.trivoo.website）
- Value / Target IP：43.156.118.130（你的云服务器公网 IP）
- TTL：保持默认或选择 30 min / 1 min
点击 Add / Save 保存，等待右侧出现绿色的 ADDED 提示。

三、第二阶段：云服务器防火墙安全配置

登录腾讯云轻量服务器控制台 -> 点击目标实例 -> 防火墙，确保以下规则已放行：

应用类型	协议	端口	策略	作用说明
Linux 登录	TCP	22	允许	SSH 远程登录维护
HTTP	TCP	80	允许	Certbot 申请 SSL 证书及 HTTP-01 验证
HTTPS	TCP	443	允许	安全加密 Web 访问及客户端 API 调用
自定义	TCP	8388	允许	已有的 Xray / Shadowsocks 梯子服务

安全注意：不要在公网防火墙中开放 3000 端口。生产环境下 3000 端口只走服务器内部回环转发，所有外网流量统一由 443 端口接入。

四、第三阶段：New API 容器化部署

1. 登录服务器并切换 root 权限

在本地终端执行：

ssh ubuntu@43.156.118.130
sudo -i

(必须通过 sudo -i 确保提示符为 root@...:~#，避免因普通权限导致 Permission Denied)

2. 初始化目录并生成专属随机密钥

# 创建持久化数据与日志目录
mkdir -p /opt/new-api/data /opt/new-api/logs
cd /opt/new-api

# 生成 64 位密码级随机安全会话密钥
echo "SESSION_SECRET=$(openssl rand -hex 32)" > .env
chmod 600 .env

3. 编写安全生产型 docker-compose.yml

cat > /opt/new-api/docker-compose.yml <<'EOF'
services:
  new-api:
    image: calciumion/new-api:latest
    container_name: new-api
    restart: unless-stopped
    command: --log-dir /app/logs

    # 严格绑定回环地址，禁止公网直连 3000
    ports:
      - "127.0.0.1:3000:3000"

    volumes:
      - ./data:/data
      - ./logs:/app/logs

    environment:
      - TZ=Asia/Shanghai
      - ERROR_LOG_ENABLED=true
      - BATCH_UPDATE_ENABLED=true
      - NODE_NAME=new-api-sg-1
      - STREAMING_TIMEOUT=300
      - "SESSION_SECRET=${SESSION_SECRET:?未设置 SESSION_SECRET，请检查 .env}"
      - SESSION_COOKIE_SECURE=true
      - SESSION_COOKIE_TRUSTED_URL=https://api.trivoo.website
      - TRUSTED_PROXIES=127.0.0.1,172.17.0.0/16

    # 内存保护上限（防止高并发下拖垮同机代理服务）
    mem_limit: 800m
EOF

4. 启动容器与状态检查

cd /opt/new-api
docker compose up -d
docker ps

回显中显示 new-api 状态为 Up 且端口为 127.0.0.1:3000->3000/tcp 即代表容器启动成功。

五、第四阶段：Nginx 反向代理与 SSL 证书自动化

1. 安装 Nginx 与 Certbot 证书套件

apt update && apt install -y nginx certbot python3-certbot-nginx

2. 写入 Nginx 站点配置

创建反向代理配置文件 /etc/nginx/sites-available/api.trivoo.website：

cat > /etc/nginx/sites-available/api.trivoo.website <<'EOF'
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    server_name api.trivoo.website;

    # 允许大文件上传（如语音转录、多模态图片）
    client_max_body_size 100m;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;

        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket 协议支持（Realtime / Responses 升级通道）
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        # 核心：关闭缓冲以支持打字机流式响应（SSE）
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 1800s;
        proxy_send_timeout 1800s;
    }
}
EOF

3. 启用站点并检查语法

ln -sf /etc/nginx/sites-available/api.trivoo.website /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

(必须看到 syntax is ok 与 test is successful)

4. 一键自动签发 Let's Encrypt 证书并启用 HTTPS

certbot --nginx -d api.trivoo.website --non-interactive --agree-tos -m admin@trivoo.website --redirect

执行完毕后出现： Congratulations! You have successfully enabled HTTPS on https://api.trivoo.website 此时证书已自动安装，并已创建 systemd 自动续期定时器。

六、第五阶段：New API 初始化与渠道配置

1. 首次访问与系统向导

浏览器访问：https://api.trivoo.website

数据库检查：自动检测出 SQLite，直接点击「下一步」；
管理员账户：设定管理员用户名和高强度密码；
完成初始化：进入控制台主界面。

2. 接入官方渠道（以 DeepSeek 官方为例）

左侧菜单栏点击 「渠道」 -> 右上角 「创建渠道」；
类型：选择 DeepSeek；
API 密钥：填入 DeepSeek 官方以 sk- 开头的 API Key；
模型：点击快捷操作中的 「填入相关模型」，框内自动出现 deepseek-chat 与 deepseek-reasoner 标签；
点击最底部 「提交」；
在渠道列表中点击该卡片右上角的 仪表盘图标（测速），出现绿色延迟（如 554ms）代表渠道通信成功。

3. 接入第三方自定义渠道（以 `apikey.fan` 聚合服务为例）

点击 「创建渠道」 -> 类型选 高级自定义（或 OpenAI 兼容）；
API 地址：填入服务商的基础网关地址（如 https://api.apikey.fan）；
API 密钥：填入该服务商提供的密钥；
模型：手动输入该上游支持的具体模型名（如 gpt-5.6-terra），按回车确认生成标签；
点击提交并点击测试图标，验证连通性。

4. 生成调用令牌（分发密钥）

左侧菜单栏点击 「常规」 -> 「API 密钥」（或「令牌」）；
点击右上角 「创建密钥」；
设定名称（如 default-token），额度设为无限或指定额度；
提交后在列表中点击 「复制」，获取专属于该网关的 sk-xxxx 令牌。

七、第六阶段：客户端接入与高频踩坑排错手册

1. 客户端标准配置示例

在任何支持第三方 API 的客户端（如 Cline、NextChat、Cherry Studio、Chatbox 等）中配置：

接口地址 / Base URL：https://api.trivoo.website/v1
API Key：填入后台生成的 sk-xxxx 令牌
模型名称：填入渠道中已有的有效模型（如 deepseek-chat 或 gpt-5.6-terra）

2. 实战高频报错与精准排错对照

❌ 错误 1：`404 Invalid URL (POST /v1/v1/messages)`

现象：客户端报错 404，请求路径出现重复的 /v1/v1。
原因：部分遵循 Anthropic / Claude 协议的客户端（如某些版本的 Cline），内部会自动为地址补全 /v1/messages。如果你在配置的 Base URL 中包含了 /v1，拼接后就会变成 /v1/v1/messages。
解决方案：将客户端的 API 地址末尾的 /v1 删掉，改为 https://api.trivoo.website。

❌ 错误 2：`503 No available channel for model xxx under group default`

现象：客户端发起调用，返回 model_not_found。
原因：客户端发送的模型请求名称（例如 gpt-5.6-terra），在 New API 的所有可用渠道模型列表中都不存在。
解决方案：
- 方案 A（改客户端）：将客户端的模型名称改为渠道真实支持的名字（如 deepseek-chat）；
- 方案 B（改网关重定向）：在 New API 对应渠道编辑页中，点击「设置模型重定向」，将外部请求的 gpt-5.6-terra 重定向映射到后端的 deepseek-chat。

❌ 错误 3：`Permission denied` / `No such file or directory`

现象：在服务器终端执行 Docker 或 Nginx 配置命令时报错。
原因：新开的 SSH 会话默认处于普通用户 ubuntu 权限。
解决方案：执行命令前务必先输入 sudo -i 切换到 root 账户。

❌ 错误 4：Spaceship 登录报 `Invalid username or password`

现象：明明输入了正确邮箱和密码，却无法登录 Spaceship。
原因：Spaceship 强制要求在第一栏输入当初注册时设置的 Username（用户名，如 Beyond），不支持直接使用邮箱登录。
解决方案：在注册邮件中查找用户名，使用纯用户名登录。

八、第七阶段：日常运维、安全加固与一键清理

1. 生产环境安全加固（必做）

关闭公开注册：进入后台 https://api.trivoo.website -> 「系统设置」 -> 「登录注册」 -> 将 「允许新用户注册」彻底关闭。 (防止域名暴露在公网后被爬虫扫描并注册账号白嫖接口额度)
SSL 自动续期确认： Certbot 已经注册了 systemd 定时任务，可通过以下命令测试自动续期机制：
```
certbot renew --dry-run
```

2. 日常启停与重启

# 暂停 New API 网关（保留所有数据，释放 CPU/内存占用）
cd /opt/new-api && docker compose stop && systemctl stop nginx

# 重新启动 New API 网关
cd /opt/new-api && docker compose start && systemctl start nginx

# 查看实时运行日志
cd /opt/new-api && docker compose logs -f --tail=100 new-api

3. 一键卸载与彻底清理（恢复纯净服务器）

如果后续需要腾空服务器，执行以下步骤可在 1 分钟内完全清理痕迹，且完全不影响服务器原有的代理与 SSH 服务：

# 1. 停止并销毁容器及持久化目录
cd /opt/new-api && docker compose down
rm -rf /opt/new-api

# 2. 卸载 Nginx 站点配置
rm -f /etc/nginx/sites-enabled/api.trivoo.website /etc/nginx/sites-available/api.trivoo.website
systemctl reload nginx

# 3. 删除 Let's Encrypt 证书记录（可选）
certbot delete --cert-name api.trivoo.website

同时登录 Spaceship 域名控制台，将 api.trivoo.website 的 A 记录直接点击删除即可。

14 KiB Raw Blame History Unescape Escape