ZC API

主题

使用与部署手册 ​

本文档覆盖四件事：

  1. 本地快速启动
  2. 生产服务器部署
  3. GitHub 驱动更新
  4. 日常运维与排障

1. 组件说明 ​

当前仓库只维护部署壳，不维护 new-api 上游源码。

项目标识：zc-api
基于 calciumion/new-api:latest 上游镜像
容器前缀：zcapi-*，环境变量前缀：ZC_API_*

核心组件：

  • zc-api: 主服务，使用官方镜像 calciumion/new-api:latest
  • postgres: 持久化配置、用户、渠道、日志等数据
  • redis: 缓存与运行态加速
  • cloudflared: 生产入口，直接把 api.geoq.help / gateway.geoq.help 指向本机 127.0.0.1:3000

当前推荐的生产入口：

  • 主入口：https://api.geoq.help
  • 备用入口：https://gateway.geoq.help

2. 本地快速启动 ​

2.1 环境要求 ​

本机需要：

  • Docker
  • Docker Compose
  • curl
  • openssl

先检查依赖：

bash
./scripts/doctor.sh

2.2 初始化环境变量 ​

复制模板：

bash
cp ".env.example" ".env"

生成随机密钥：

bash
./scripts/generate-secrets.sh

把输出写回 .env。

至少确认这些字段：

  • ZC_API_PUBLIC_URL
  • POSTGRES_PASSWORD
  • REDIS_PASSWORD
  • SESSION_SECRET
  • INIT_ADMIN_PASSWORD

本地调试时可以这样填：

env
ZC_API_PUBLIC_URL=http://127.0.0.1:3000

生产环境建议填写正式域名：

env
ZC_API_PUBLIC_URL=https://api.geoq.help

2.3 启动 ​

bash
./scripts/up.sh

检查服务：

bash
./scripts/check.sh

2.4 初始化管理员 ​

bash
./scripts/init-admin.sh

初始化后访问：

  • 本地：http://127.0.0.1:3000
  • 生产：https://api.geoq.help

3. 后台首次配置 ​

3.1 添加上游渠道 ​

登录后台后：

  1. 进入“渠道管理”
  2. 新建渠道
  3. 选择供应商类型
  4. 填写上游 Base URL 和 API Key
  5. 绑定支持的模型
  6. 点击测试

3.2 常见错误 ​

如果测试时报：

text
模型 gpt-5.4 倍率或价格未配置

处理方式有两种：

  • 临时方案：开启“自用模式”
  • 正式方案：在后台补齐模型倍率和价格配置

3.3 建议立刻调整的后台项 ​

  • 关闭公开注册
  • 打开分组和模型限制
  • 高成本模型单独分组
  • 根据上游成本配置倍率和价格
  • 把 ServerAddress 设为 https://api.geoq.help

4. 生产部署方式 ​

当前推荐生产方式：

  • 代码来源：GitHub 仓库 git@github.com:hidingable/api-gateway.git
  • 服务编排：docker compose
  • 对外入口：cloudflared tunnel
  • 源站监听：仅 127.0.0.1:3000
  • 不再依赖 nginx

当前生产服务器：

  • 服务器别名：dify
  • IP 地址：118.196.83.124
  • 主机名：iv-yefdpn6yo0ay8n8lgb8w
  • 系统版本：Ubuntu 24.04 LTS
  • SSH 连接：ssh dify（需预先配置 ~/.ssh/config）

4.1 服务器目录约定 ​

生产目录：

bash
/opt/projects/zc-api

目录内会包含：

  • Git 工作树
  • .env
  • data/
  • logs/

其中：

  • .env
  • data/
  • logs/

不会进入 Git 仓库。

4.2 首次在服务器上部署 ​

如果服务器还没有目录：

bash
mkdir -p /opt/projects/zc-api
cd /opt/projects/zc-api
git init
git branch -M main
git remote add origin git@github.com:hidingable/api-gateway.git

如果服务器已经有目录但没有 Git：

bash
cd /opt/projects/zc-api
git init
git branch -M main
git remote add origin git@github.com:hidingable/api-gateway.git

如果目录所有者不是当前登录用户，Git 可能会报 dubious ownership，执行：

bash
git config --global --add safe.directory /opt/projects/zc-api

首次拉取：

bash
cd /opt/projects/zc-api
git fetch origin
git reset --hard origin/main

准备环境变量：

bash
cp ".env.example" ".env"

填好 .env 后启动：

bash
./scripts/up.sh
./scripts/init-admin.sh

4.3 生产环境 .env 建议 ​

关键项至少包括：

env
COMPOSE_PROJECT_NAME=zcapi-mvp
TZ=Asia/Shanghai
ZC_API_PORT=3000
ZC_API_PUBLIC_URL=https://api.geoq.help

注意：

  • ZC_API_PORT 仍然写 3000
  • 实际暴露方式由 docker-compose.yml 控制为 127.0.0.1:3000:3000
  • 外部访问通过 Cloudflare Tunnel，不需要公网开放 3000

5. Cloudflare Tunnel 配置 ​

当前生产方案假设你已经有可用 tunnel，并把这两个 host 指到本机：

  • api.geoq.help -> http://localhost:3000
  • gateway.geoq.help -> http://localhost:3000

典型配置如下：

yaml
tunnel: <your-tunnel-id>
credentials-file: /root/.cloudflared/<your-tunnel-id>.json

ingress:
  - hostname: api.geoq.help
    service: http://localhost:3000
  - hostname: gateway.geoq.help
    service: http://localhost:3000
  - service: http_status:404

对应的 systemd 服务一般是：

bash
systemctl status cloudflared

6. GitHub 驱动更新 ​

6.1 推荐方式 ​

服务器更新统一执行：

bash
cd /opt/projects/zc-api
./scripts/redeploy.sh

脚本内部会做三件事：

  1. git fetch origin
  2. git reset --hard origin/main
  3. ./scripts/up.sh

6.2 为什么用这种方式 ​

优点：

  • 不依赖本地 rsync
  • 服务器状态可回放
  • 回滚简单
  • 变更路径统一

6.3 服务器访问 GitHub 的前提 ​

服务器需要配置 deploy key，并且仓库 origin 可读。

如果 git fetch origin 报：

text
Repository not found

优先检查：

  • deploy key 是否加到了仓库
  • origin 是否写对
  • core.sshCommand 是否指定了正确私钥

7. 日常运维命令 ​

7.1 启动与停止 ​

启动：

bash
cd /opt/projects/zc-api
./scripts/up.sh

停止：

bash
cd /opt/projects/zc-api
./scripts/down.sh

7.2 查看状态 ​

bash
cd /opt/projects/zc-api
docker compose ps

7.3 查看健康检查 ​

bash
curl -sS http://127.0.0.1:3000/api/status

7.4 查看 Tunnel 状态 ​

bash
# 查看你的 tunnel 信息（示例：geoq-newapi）
cloudflared tunnel info <your-tunnel-name>
systemctl status cloudflared --no-pager -l

7.5 查看容器日志 ​

bash
cd /opt/projects/zc-api
docker compose logs -f zc-api

7.6 外网验证 ​

bash
curl -I https://api.geoq.help
curl -I https://gateway.geoq.help

8. 回滚 ​

如果某次更新有问题，可以直接回滚到上一个提交：

bash
cd /opt/projects/zc-api
git log --oneline -n 5
git reset --hard <commit-id>
./scripts/up.sh

回滚后重点验证：

  • docker compose ps
  • curl http://127.0.0.1:3000/api/status
  • curl -I https://api.geoq.help

9. 常见问题排查 ​

9.1 ./scripts/redeploy.sh: Permission denied ​

原因：

  • 脚本没有执行位

处理：

bash
chmod +x scripts/redeploy.sh
git add scripts/redeploy.sh
git commit -m "fix: make redeploy script executable"
git push origin main

9.2 detected dubious ownership in repository ​

原因：

  • Git 认为当前目录所有者和执行用户不匹配

处理：

bash
git config --global --add safe.directory /opt/projects/zc-api

9.3 模型倍率或价格未配置 ​

原因：

  • zc-api 后台没配对应模型的倍率或价格

处理：

  • 开启自用模式，或
  • 在后台补齐模型价格、倍率

9.4 域名能解析，但打不开 ​

优先按这个顺序查：

  1. cloudflared tunnel info <your-tunnel-name> （检查 tunnel 状态）
  2. systemctl status cloudflared
  3. curl http://127.0.0.1:3000/api/status
  4. docker compose ps

9.5 git fetch origin 失败 ​

优先检查：

  • deploy key 是否失效
  • origin 地址是否正确
  • GitHub 仓库权限是否变更

10. 使用方验证 ​

在后台创建一个测试 Token 后，可以直接用下面命令验证代理链路：

bash
curl "${ZC_API_PUBLIC_URL%/}/v1/chat/completions" \
  -H "Authorization: Bearer <YOUR_ZC_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<YOUR_MODEL_NAME>",
    "messages": [
      {
        "role": "user",
        "content": "ping"
      }
    ]
  }'

如果你用的是 OpenAI SDK，只需要把：

  • base_url 指向 https://api.geoq.help/v1
  • api_key 换成你在 zc-api 后台创建的 Token

11. 备份建议 ​

最少备份三类东西：

  • .env
  • data/postgres
  • data/redis

如果要做正式生产，建议再补：

  • 定时数据库备份
  • Cloudflare Tunnel 配置备份
  • 提交级别回滚记录

12. 生产检查清单 ​

上线前至少确认：

  • ZC_API_PUBLIC_URL 已设为正式域名
  • docker compose ps 全部健康
  • curl http://127.0.0.1:3000/api/status 正常
  • curl -I https://api.geoq.help 返回 200
  • 管理后台已添加上游渠道
  • 已关闭公开注册
  • 已配置模型价格和倍率
  • .env、data/、logs/ 未进入 Git

基于 new-api 二次开发，AGPL-3.0 协议

© 2026 GeoQ