一、先理解 Sub2API 里的三个对象

最容易犯的错误是把“上游账号凭据”当成“API Key”交给客户端。正确做法是：账号只进后台，客户端只拿 Sub2API 生成的 Key。

二、Linux 服务器搭建（推荐）

2.1 准备域名、系统和端口

准备一台 Debian 11/12 或 Ubuntu 22.04/24.04 服务器、一个解析到服务器的域名，并开放 SSH 以及 Web 端口。生产环境建议使用 HTTPS；如果只是局域网测试，可以先用服务器 IP 和 HTTP。

# 查看架构，下载发行包时要选 amd64 或 arm64
uname -m

# 防火墙（使用 ufw 时）
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

2.2 选择安装方式

方式 A：Docker Compose。这是最省心的方式。下载 Sub2API 官方仓库或 Release 中的 compose 文件，进入目录后执行（如果当前 Release 没有 compose 文件，就改用下面的二进制方式）：

git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api
cp .env.example .env
# 按 .env.example 的注释填写域名、数据库、Redis、随机密钥等必填项
nano .env
docker compose up -d
docker compose ps
docker compose logs -f --tail=100

如果发行版提供的是预编译二进制，也可以使用方式 B：

sudo mkdir -p /opt/sub2api
cd /opt/sub2api
# 将与你的 CPU 架构匹配的 sub2api 文件和 .env.example 放到这里
sudo chmod +x ./sub2api
sudo cp .env.example .env
sudo nano .env
sudo ./sub2api

二进制方式通常需要你自己准备 PostgreSQL 和 Redis；Docker 方式一般会在 compose 中一并编排。不要照抄别人的数据库密码和 JWT/加密密钥，必须换成自己的随机值。

2.3 反向代理和 HTTPS

让 Nginx/Caddy 把域名转发到 Sub2API 的监听端口。端口以日志或 `.env` 中的配置为准；本机已有服务的典型形态如下：

server {
    listen 443 ssl http2;
    server_name api.example.com;

    location / {
        proxy_pass http://127.0.0.1:52880;
        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;
    }
}

配置完成后先运行 nginx -t，再 reload。浏览器打开 https://api.example.com，能看到登录页就说明入口已经通了。

三、Windows 搭建与本地运行

Windows 最简单的方案是安装 Docker Desktop，勾选 WSL 2 后，在 PowerShell 中运行与 Linux 相同的 compose 命令：

git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api
copy .env.example .env
notepad .env
docker compose up -d
docker compose ps

访问 http://localhost:端口。如果只是给自己使用，Windows 本地部署足够；如果要让手机、办公室电脑或朋友使用，建议把服务放在 Linux 服务器上，并通过 HTTPS 暴露，而不是把 Windows 的管理端口直接映射到公网。

Windows 也可以直接运行 Release 中的 sub2api.exe。把它和 .env 放在同一目录，在 PowerShell 执行：

cd C:\sub2api
.\sub2api.exe

若窗口一闪而过，请在 PowerShell 中运行并保留报错信息；最常见原因是端口被占用、数据库地址错误或缺少运行库。

四、导入账号并创建自己的 API

4.1 首次登录

1. 打开 Sub2API 域名或本机地址，使用安装时设置的管理员账号登录。
2. 先进入“系统设置/安全设置”，修改初始管理员密码，确认站点 URL、时区和默认模型。
3. 在“账号管理/上游账号”中点击“添加账号”。

4.2 添加上游账号

1. 选择服务商或协议类型。页面通常会提供 OAuth 授权、Access Token、Refresh Token 或 Cookie 等选项。
2. 如果是 OAuth，点击授权链接，在新窗口完成登录，再把回调结果返回后台；如果是 Token 模式，粘贴对应字段并保存。
3. 给账号写一个容易辨认的备注，例如“主账号-1”“备用账号-德国”，然后点击“测试/验证”。
4. 状态显示“可用”后，再把它绑定到一个模型或渠道。不要一上来导入几十个账号，先用一个账号完成闭环。

4.3 创建 API Key

1. 打开“API 令牌/密钥管理”，点击“新建”。
2. 设置名称、有效期、可用模型、并发/额度（如果你的版本支持），然后保存。
3. 令牌通常只完整显示一次，请立即复制到密码管理器。示例统一写成 sk-sub2api-xxxxxxxx，不要把真实 Key 写进脚本仓库。

到这里，你需要记住两个值：

接口地址： https://api.example.com/v1
API Key：  sk-sub2api-xxxxxxxx

五、CLI 端怎么用

5.1 先用 curl 验证接口

curl https://api.example.com/v1/models \
  -H "Authorization: Bearer sk-sub2api-xxxxxxxx"

curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer sk-sub2api-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"在后台显示的模型名",
    "messages":[{"role":"user","content":"你好，请回复一句测试语。"}]
  }'

第一个请求返回模型列表、第二个请求返回正常回答，说明账号、路由、Key 和网络全部打通。

5.2 OpenAI 兼容 CLI / Python

# Linux/macOS
export OPENAI_BASE_URL="https://api.example.com/v1"
export OPENAI_API_KEY="sk-sub2api-xxxxxxxx"

# Windows PowerShell（永久写入当前用户环境变量）
[Environment]::SetEnvironmentVariable("OPENAI_BASE_URL","https://api.example.com/v1","User")
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY","sk-sub2api-xxxxxxxx","User")

重启终端后，支持 OpenAI SDK 的 CLI 或脚本就会自动使用 Sub2API。若某个工具自己拼接了 /v1，则环境变量里不要重复写两次；以该工具的帮助文档为准。

5.3 Codex CLI / Claude Code

这类工具的变量名可能随版本变化，思路不变：把“兼容接口地址”填到 Base URL，把 Sub2API 生成的 Key 填到 API Key/Token。Codex 或其他 OpenAI 兼容 CLI 可以直接使用下面的配置；Claude Code 只有在当前 Sub2API 版本提供 Anthropic 兼容入口时才使用对应变量。

# Codex 或其他 OpenAI 兼容 CLI
export OPENAI_BASE_URL="https://api.example.com/v1"
export OPENAI_API_KEY="sk-sub2api-xxxxxxxx"

# Claude Code（仅当当前版本支持自定义 Anthropic Base URL）
export ANTHROPIC_BASE_URL="https://api.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-sub2api-xxxxxxxx"

如果 CLI 报“模型不存在”，先执行 /v1/models 查看 Sub2API 实际返回的模型 ID，再把配置中的模型名改成完全一致的值。

六、常见问题与安全收尾

最后做四件事：给管理后台启用 HTTPS；限制管理端口只允许自己的 IP；定期备份数据库和 .env（密钥单独加密保存）；为不同项目创建不同 API Key，出现泄露时只撤销一枚 Key。