Sub2API 管理员操作手册

本文只记录管理员日常需要执行的操作。

快速入口

要做的事情	查看章节
服务器重启后恢复服务	1. 启动与恢复
更新 Sub2API 版本	1.5 更新 Sub2API 版本
首次部署或修改代理端口	2. 配置项目网络
排查代理探测失败	2.5 排查代理探测失败
在 Sub2API 后台添加代理	3. 后台配置代理
更多	4. 更多

当前配置

系统账号：collab
项目目录：/data/collab/Projects/sub2api
Compose 文件：deploy/docker-compose.local.yml
平台端口：23434
Clash 端口：127.0.0.1:49872
socat 监听：172.17.0.1:49872
容器代理：http://host.docker.internal:49872
screen 会话：clash

注意：

collab 密码、Clash 订阅地址和项目密钥从负责人处获取，不要写入本文或 Git。
当前使用 screen 保持 socat 运行。SSH 断开不影响，但服务器重启后需要重新执行第 1 节。
Clash 保持 allow-lan: false，不要把 socat 绑定到 0.0.0.0。

1. 启动与恢复

1.1 登录 collab

su - collab

1.2 在screen中启动 Clash

clashoff
clashon

测试 Clash：

curl -sS \
  --proxy http://127.0.0.1:49872 \
  -o /dev/null \
  -w 'HTTP %{http_code}\n' \
  https://github.com/

预期输出：

HTTP 200

如果是第一次使用 Clash，请参考文档：HUSTNLP Server Clash 使用教程。

1.3 启动 socat relay

先检查 relay 是否已经运行：

screen -ls
pgrep -af socat
ss -ltnp | grep 49872

如果已经看到下面两个监听，不要重复启动：

127.0.0.1:49872  mihomo
172.17.0.1:49872 socat

如果 socat 没有运行，重新进入上一步骤的screen（开启了clash的）：

screen -r clash

在 screen 中执行：

socat -d -d \
  TCP-LISTEN:49872,bind=172.17.0.1,reuseaddr,fork \
  TCP:127.0.0.1:49872

保持 socat 运行，按下面的组合键退出 screen：

先按 Ctrl+a，松开，再按 d

以后需要回到该窗口时执行：

screen -r clash

测试 relay：

curl -sS \
  --proxy http://172.17.0.1:49872 \
  -o /dev/null \
  -w 'HTTP %{http_code}\n' \
  https://github.com/

预期输出 HTTP 200。

1.4 启动 Sub2API

cd /data/collab/Projects/sub2api/deploy
docker compose -f docker-compose.local.yml up -d --force-recreate

检查服务（也可以访问前端http://222.20.99.38:23434，服务器ip+设置的服务端口）：

docker compose -f docker-compose.local.yml ps
curl -fsS http://127.0.0.1:23434/health

健康接口应输出：

{"status":"ok"}

最后从容器测试代理：

docker exec sub2api sh -lc '
curl -sS \
  --proxy http://host.docker.internal:49872 \
  -o /dev/null \
  -w "HTTP %{http_code}\n" \
  https://github.com/
'

预期输出 HTTP 200。测试时优先使用 curl，不要用 wget 判断代理是否正常。

1.5 更新 Sub2API 版本

进入部署目录并拉取最新的 Sub2API 镜像，然后仅重新创建 sub2api 服务：

cd /data/collab/Projects/sub2api/deploy

docker compose -f docker-compose.local.yml pull sub2api
docker compose -f docker-compose.local.yml up -d --force-recreate --no-deps sub2api

2. 配置项目网络

只有首次部署、Clash 端口变化或 relay 地址变化时，才需要执行本节。

2.1 确认 host.docker.internal 地址

当前地址是 172.17.0.1。运行中的容器可以这样确认：

docker exec sub2api sh -lc \
  "grep '[[:space:]]host.docker.internal' /etc/hosts"

当前预期输出：

172.17.0.1 host.docker.internal

如果输出了其他地址，socat 命令中的 bind=172.17.0.1 也要改成该地址。

2.2 修改 Compose

打开配置文件：

cd /data/collab/Projects/sub2api
vim deploy/docker-compose.local.yml

确认 sub2api 服务包含：

extra_hosts:
  - "host.docker.internal:host-gateway"

确认下面三项端口一致：

- HTTP_PROXY=${SUB2API_HTTP_PROXY:-http://host.docker.internal:49872}
- HTTPS_PROXY=${SUB2API_HTTPS_PROXY:-http://host.docker.internal:49872}
- UPDATE_PROXY_URL=${UPDATE_PROXY_URL:-http://host.docker.internal:49872}

保存后检查 Compose 语法：

cd /data/collab/Projects/sub2api/deploy
docker compose -f docker-compose.local.yml config --quiet

命令没有输出表示语法正常。

2.3 应用配置

首次部署，启动全部服务：

cd /data/collab/Projects/sub2api/deploy
docker compose -f docker-compose.local.yml up -d --force-recreate

如果只修改了代理配置，只重新创建 Sub2API 容器：

docker compose -f docker-compose.local.yml up -d --force-recreate sub2api

不需要执行 docker build。只执行 docker restart sub2api 不能应用新的 Compose 环境变量。

2.4 修改端口时需要同步的地方

如果以后将 49872 改为其他端口，必须同时修改：

Clash mixed 端口。
socat 的 TCP-LISTEN 和 TCP:127.0.0.1 端口。
Compose 的 HTTP_PROXY、HTTPS_PROXY、UPDATE_PROXY_URL。
Sub2API 管理员控制台“IP管理”中“VPN”的“端口”。

改完后重新执行第 1.3、1.4 节的测试。

2.5 排查代理探测失败

如果出现下面的错误：

all probe URLs failed, last error: proxy connection failed: Get "http://api64.ipify.org?format=json": proxyconnect tcp: dial tcp: lookup host.docker.internal on 127.0.0.11:53: no such host

通常是 Clash 端口配置不一致导致的。修改端口时，必须同时修改以下三处：

Clash 的 mixed 端口。
socat 命令中 TCP-LISTEN 和 TCP:127.0.0.1 的端口。
docker-compose.local.yml 中 HTTP_PROXY、HTTPS_PROXY 和 UPDATE_PROXY_URL 的端口。

还需要进入 Sub2API 管理员控制台，在“IP管理”中编辑“VPN”，将“端口”同步修改为 Clash 使用的端口。修改 Compose 配置后，按照第 2.3 节重新创建 sub2api 容器。

如果端口已经一致，但错误中仍然出现 lookup host.docker.internal，请按照第 2.1、2.2 节检查 host.docker.internal 地址以及 Compose 中的 extra_hosts 配置。

3. 后台配置代理

Compose 中的全局代理不一定覆盖 AI 网关请求，因此需要在 Sub2API 中给账号绑定代理。

3.1 在 IP 管理中添加代理

important

修改 Clash 端口后，还必须进入管理员控制台的“IP管理”，编辑“VPN”，并将“端口”同步修改为 49872。

使用管理员账号登录 Sub2API。
进入“IP管理”。
点击“添加代理”。
名称填写 host-clash-relay。
协议选择 HTTP。
主机填写 host.docker.internal。
端口填写 49872。
用户名、密码留空。
保存。
点击“测试连接”或“测试代理”。

测试应显示代理连接正常。不要填写 127.0.0.1，因为请求是从 Docker 容器中发出的。

3.2 给 AI 账号绑定代理

进入“账号管理”。
添加账号，或编辑已有账号。
在“代理”字段选择 host-clash-relay。
保存账号。
如果是 OAuth 账号，在选好代理后完成授权或重新授权。
发起一次真实 AI 请求，确认账号状态和请求日志正常。

OpenAI、Claude、Gemini、Grok 等需要境外访问的账号都应检查代理绑定。

4. 更多

更多操作可以参考以下项目文档：