运维手册

New API 运维手册

AI Gateway Runbook · Oracle Cloud ARM · Ubuntu 24.04

自建 AI 网关 new-api 的架构、日常运维命令、Cloudflare 配置、安全加固、面板操作与故障排查手册。全站经 Cloudflare 代理，源站 IP 不对外暴露，容器仅监听本机回环地址。

服务器 Oracle Cloud ARM (Ubuntu 24.04)域名 api.主域名部署日期 2026-06-04文档版本 v1.0

一架构总览

用户浏览器 │ HTTPS (TLS 1.3) ▼ Cloudflare 边缘节点（橙色云，隐藏源站真实 IP <Oracle 服务器 IP>） │ HTTPS (Cloudflare Origin Certificate, Full Strict) ▼ Oracle Cloud 防火墙（仅开放 80/443） │ ▼ 宿主机 Nginx（进程管理，非 systemd） │ 内部转发 → 127.0.0.1:3010 ▼ new-api Docker 容器（127.0.0.1:3010:3000，公网不可达） │ ▼ /home/ubuntu/new-api-data/one-api.db（SQLite 持久化）

二关键信息速查

项目	内容
服务器 IP	Oracle 服务器 IP
SSH 连接	`ssh ubuntu@<Oracle 服务器 IP>`（端口 22）
访问地址	https://api.主域名
管理后台	https://api.主域名（右上角登录）
API 接入地址	https://api.主域名/v1
容器内部端口	127.0.0.1:3010（仅本机可达，公网不可达）
数据目录	/home/ubuntu/new-api-data/
项目目录	/home/ubuntu/new-api/
nginx 反代配置	/etc/nginx/sites-available/new-api
nginx 代理参数	/etc/nginx/snippets/proxy-params.conf
SSL 证书	/etc/nginx/certs/主域名/origin.pem
SSL 私钥	/etc/nginx/certs/主域名/origin-key.pem

三文件结构

/home/ubuntu/new-api/
├── docker-compose.yml      ← Docker 编排文件
└── .env                    ← 环境变量（含 SESSION_SECRET，权限 600）

/home/ubuntu/new-api-data/
└── one-api.db              ← SQLite 数据库（所有数据在这里）

/etc/nginx/
├── sites-available/new-api     ← nginx 反代配置（源文件）
├── sites-enabled/new-api       ← 软链接（指向上面的文件）
├── snippets/proxy-params.conf  ← 代理参数公共片段
└── certs/<主域名>/
    ├── origin.pem              ← Cloudflare Origin Certificate
    └── origin-key.pem          ← 私钥（权限 600，严格保护）

四日常运维命令

4.1 查看服务状态

# 查看容器运行状态（STATUS 应为 healthy）
cd ~/new-api && docker compose ps

# 查看实时日志
cd ~/new-api && docker compose logs -f --tail=50

# 查看 nginx 访问日志
sudo tail -f /var/log/nginx/new-api.access.log

# 查看 nginx 错误日志
sudo tail -f /var/log/nginx/new-api.error.log

# 检查 nginx 进程
ps aux | grep nginx | grep -v grep

4.2 启动 / 停止 / 重启

# 启动容器
cd ~/new-api && docker compose up -d

# 停止容器（数据不丢失）
cd ~/new-api && docker compose down

# 重启容器
cd ~/new-api && docker compose restart

# 重载 nginx（修改配置后执行，不中断现有连接）
sudo nginx -s reload

# 测试 nginx 配置语法（重载前先测试）
sudo nginx -t

4.3 更新 new-api 版本

cd ~/new-api

# 拉取最新镜像
docker compose pull

# 用新镜像重新启动
docker compose up -d

# 确认新版本已运行
docker compose logs --tail=10

4.4 数据备份与恢复

# 手动备份数据库
cp ~/new-api-data/one-api.db ~/new-api-backup-$(date +%Y%m%d-%H%M).db

# 查看所有备份
ls -lh ~/new-api-backup-*.db

# 设置每日自动备份（执行一次永久生效，凌晨 2 点备份，保留最近 7 份）
(crontab -l 2>/dev/null; echo "0 2 * * * cp ~/new-api-data/one-api.db ~/new-api-backup-\$(date +\%Y\%m\%d).db && find ~ -name 'new-api-backup-*.db' -mtime +7 -delete") | crontab -

# 验证定时任务已添加
crontab -l

# 恢复数据（替换日期为实际备份文件名）
cd ~/new-api && docker compose down
cp ~/new-api-backup-20260604.db ~/new-api-data/one-api.db
docker compose up -d

五Cloudflare 配置说明

5.1 DNS 配置

类型	名称	内容	代理状态
A	api	Oracle 服务器 IP	已代理（橙色云）

💡

⚠️ 代理状态必须是「已代理」（橙色云朵），选灰色云会直接暴露源站真实 IP。

5.2 SSL/TLS 配置

加密模式：完整（严格）/ Full (Strict)
Origin Certificate：已安装在服务器，有效期 15 年
证书覆盖范围：*.<主域名> 和 <主域名>（通配符，api/panel 等子域均覆盖）

5.3 SSL 证书续签（约 15 年后）

1. Cloudflare Dashboard → <主域名> → SSL/TLS → Origin Server
2. 撤销旧证书 → Create Certificate（重新生成）
3. 将新证书内容写入服务器：
   sudo nano /etc/nginx/certs/<主域名>/origin.pem
   sudo nano /etc/nginx/certs/<主域名>/origin-key.pem
4. 重载 nginx：sudo nginx -s reload

六安全配置说明

6.1 端口安全验证

# 验证 3010 只绑定到本地（每次服务器重启后建议检查一次）
sudo ss -tlnp | grep 3010

# 正确输出（安全）：
# 127.0.0.1:3010  ← 只有本地可达
#
# 危险输出（立即检查 docker-compose.yml）：
# 0.0.0.0:3010    ← 公网可达，不安全！

6.2 nginx 安全特性（已配置）

特性	说明
登录速率限制	/api/user/login 每分钟最多 5 次，超出返回 429
X-Frame-Options	DENY，防止点击劫持
X-Content-Type-Options	nosniff，防 MIME 嗅探
Strict-Transport-Security	max-age=31536000，强制 HTTPS
server_tokens	off，隐藏 nginx 版本号
SSL 协议	仅 TLSv1.2 + TLSv1.3

6.3 密码与 Token 安全建议

管理员密码：16 位以上，含大小写字母 + 数字 + 特殊符号
为每个应用/用户单独创建 Token，不共用同一个
后台设置中关闭「允许新用户注册」

七new-api 面板操作指南

7.1 添加 AI 供应商渠道

登录后台 → 渠道 → 添加渠道
├── 类型：选择对应供应商（OpenAI / Anthropic / 智谱 / DeepSeek 等）
├── 名称：自定义（如 OpenAI-GPT4）
├── 密钥：填入对应供应商的 API Key
└── 保存后点「测试」验证是否可用

7.2 创建用户 Token

后台 → 令牌 → 添加令牌
├── 名称：按用途命名（如 cursor-personal / app-prod）
├── 额度：按需设置（-1 为无限制）
├── 模型限制：可指定允许使用的模型
└── 复制生成的 sk-xxx Token 保存好

7.3 客户端（Cursor / ChatBox 等）接入配置

API Base URL : https://api.<主域名>/v1
API Key      : 填写上面创建的 Token（sk-xxx）
模型名称     : 与原始供应商相同（如 gpt-4o、claude-sonnet-4-5 等）

7.4 关闭公开注册

后台 → 系统设置 → 通用设置 → 关闭「允许新用户注册」→ 保存

八故障排查

问题：访问 https://api.主域名打不开

# Step 1：检查容器是否在运行
cd ~/new-api && docker compose ps

# Step 2：查看容器错误日志
docker compose logs --tail=30

# Step 3：检查 nginx 进程
ps aux | grep nginx | grep -v grep

# Step 4：测试内部链路
curl -s http://127.0.0.1:3010/api/status

# Step 5：如果容器挂了，重新启动
docker compose up -d

# Step 6：如果 nginx 挂了
sudo nginx

问题：修改 nginx 配置后不生效

sudo nginx -t          # 先测试语法
sudo nginx -s reload   # 语法正确后重载

问题：容器状态一直是 starting，不变 healthy

docker compose logs    # 查看启动报错原因
ls -la ~/new-api-data/ # 检查数据目录权限
chmod 755 ~/new-api-data/
docker compose restart

问题：服务器重启后服务没恢复

# 检查 nginx
ps aux | grep nginx | grep -v grep
# 没有进程则启动：
sudo nginx

# 检查容器
cd ~/new-api && docker compose ps
# 没有运行则启动：
docker compose up -d

# 让 nginx 开机自动启动（执行一次）
sudo systemctl enable nginx

九服务器重启后恢复顺序

# 1. 启动 nginx
sudo nginx

# 2. 启动容器
cd ~/new-api && docker compose up -d

# 3. 验证内部链路
curl -s http://127.0.0.1:3010/api/status

# 4. 验证外部访问
curl -s -o /dev/null -w "HTTP状态码: %{http_code}\n" https://api.<主域名>/api/status
# 返回 200 则一切正常

十定期维护清单

每月

# 更新 new-api
cd ~/new-api && docker compose pull && docker compose up -d

# 清理旧镜像（释放磁盘）
docker image prune -f

# 检查磁盘使用
df -h ~/

每季度

检查管理员密码，必要时轮换
检查各 AI 渠道 API Key 是否正常（后台 → 渠道 → 测试）
回顾 nginx 访问日志排查异常：sudo tail -200 /var/log/nginx/new-api.access.log

十一部署安全验证清单

网络暴露
[✓] 3010 端口仅绑定 127.0.0.1（已验证）
[✓] 公网无法直接访问 3010 端口（已验证）
[✓] 80/443 由 nginx 统一管理

HTTPS 加密
[✓] 全站强制 HTTPS（HTTP 301 → HTTPS）
[✓] Cloudflare Full (Strict) 端到端加密
[✓] Cloudflare Origin Certificate 已安装（*.<主域名> 通配符）
[✓] TLS 1.2 / 1.3 only

IP 保护
[✓] Cloudflare 橙色云代理已启用
[✓] 解析结果为 Cloudflare IP，非源站 <Oracle 服务器 IP>

数据持久化
[✓] SQLite 挂载到 /home/ubuntu/new-api-data/
[✓] 容器重启/删除不影响数据

应用安全（待手动完成）
[ ] 关闭公开注册（后台 → 系统设置）
[ ] 设置每日自动备份（见第四章 4.4）
[ ] 为每个应用创建独立 Token

文档版本：v1.0 | 生成日期：2026-06-04