test/NewAPI搭建与上线完整实战指南.md

# 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 解析配置](#二第一阶段域名注册与-dns-解析配置)
- [三、第二阶段：云服务器防火墙安全配置](#三第二阶段云服务器防火墙安全配置)
- [四、第三阶段：New API 容器化部署](#四第三阶段new-api-容器化部署)
- [五、第四阶段：Nginx 反向代理与 SSL 证书自动化](#五第四阶段nginx-反向代理与-ssl-证书自动化)
- [六、第五阶段：New API 初始化与渠道配置](#六第五阶段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 ]   [ 自定义第三方聚合上游 ]
```

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

---

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

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

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

---

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

登录 [腾讯云轻量服务器控制台](https://console.cloud.tencent.com/lighthouse) -> 点击目标实例 -> **防火墙**，确保以下规则已放行：

| 应用类型 | 协议 | 端口 | 策略 | 作用说明 |
| :--- | :--- | :--- | :--- | :--- |
| 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 权限
在本地终端执行：
```bash
ssh ubuntu@43.156.118.130
sudo -i
```
*(必须通过 `sudo -i` 确保提示符为 `root@...:~#`，避免因普通权限导致 Permission Denied)*

### 2. 初始化目录并生成专属随机密钥
```bash
# 创建持久化数据与日志目录
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
```bash
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. 启动容器与状态检查
```bash
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 证书套件
```bash
apt update && apt install -y nginx certbot python3-certbot-nginx
```

### 2. 写入 Nginx 站点配置
创建反向代理配置文件 `/etc/nginx/sites-available/api.trivoo.website`：
```bash
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. 启用站点并检查语法
```bash
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
```bash
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`
1. **数据库检查**：自动检测出 SQLite，直接点击「下一步」；
2. **管理员账户**：设定管理员用户名和高强度密码；
3. **完成初始化**：进入控制台主界面。

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

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

### 4. 生成调用令牌（分发密钥）
1. 左侧菜单栏点击 **「常规」 -> 「API 密钥」**（或「令牌」）；
2. 点击右上角 **「创建密钥」**；
3. 设定名称（如 `default-token`），额度设为无限或指定额度；
4. 提交后在列表中点击 **「复制」**，获取专属于该网关的 `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 定时任务，可通过以下命令测试自动续期机制：
  ```bash
  certbot renew --dry-run
  ```

### 2. 日常启停与重启
```bash
# 暂停 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 服务**：

```bash
# 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 记录直接点击删除即可。