# 在 AWS 日本区部署 Sub2API，并通过 IPRoyal 日本住宅代理连接 Claude Code
本文记录如何在 AWS 日本区域的 Ubuntu 服务器上部署 Sub2API，并将 Sub2API 访问上游模型服务的请求通过 IPRoyal 日本住宅代理转发。
这样可以实现：
* Claude Code 在本地连接自己的 Sub2API
* Sub2API 部署在 AWS 日本区域
* 只有访问上游模型服务的流量经过住宅代理
* 数据库、Redis、Docker 和服务器其他流量保持直连
* 对外只开放 HTTPS，不直接暴露 Sub2API 的 8080 端口
需要注意，代理只能改变服务器连接上游服务时的网络出口，不能保证账号不会触发平台限制。账号授权、使用频率、并发量、登录环境和平台服务条款仍然需要自行遵守。
—
## 一、准备服务器
本文环境：
“`text
服务器：AWS EC2
区域：日本东京
系统：Ubuntu
应用：Sub2API
代理：IPRoyal 日本住宅代理
客户端：Claude Code
“`
建议在 AWS 安全组中先配置以下端口：
“`text
22 仅允许自己的固定 IP
80 允许公网访问
443 允许公网访问
8080 不对公网开放
“`
如果暂时还没有配置域名，可以在安装阶段临时开放 8080，但完成 Nginx 配置后应立即关闭。
—
## 二、安装 Docker 和 Docker Compose
先切换到 root 用户：
“`bash
sudo -i
“`
安装 Docker、curl 和必要组件：
“`bash
apt update
apt install -y docker.io curl ca-certificates
“`
启动 Docker，并设置为开机自动启动：
“`bash
systemctl enable –now docker
“`
检查 Docker：
“`bash
docker version
“`
创建 Docker Compose 插件目录：
“`bash
mkdir -p /usr/local/lib/docker/cli-plugins
“`
下载 Docker Compose：
“`bash
curl -SL \
“https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)” \
-o /usr/local/lib/docker/cli-plugins/docker-compose
“`
添加执行权限：
“`bash
chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
“`
检查版本：
“`bash
docker compose version
“`
Docker 官方更推荐通过软件仓库安装 Compose 插件；手动下载的 Compose 不会自动升级，需要以后自行更新。
—
## 三、安装 Sub2API
创建部署目录：
“`bash
mkdir -p /opt/sub2api-deploy
cd /opt/sub2api-deploy
“`
执行 Sub2API 官方部署脚本：
“`bash
curl -sSL \
https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh \
| bash
“`
部署脚本会自动生成：
“`text
Docker Compose 配置
.env 环境变量
PostgreSQL 密码
JWT_SECRET
TOTP_ENCRYPTION_KEY
数据存储目录
“`
Sub2API 官方推荐使用该脚本部署，并使用本地目录保存 PostgreSQL、Redis 和应用数据，方便后续备份与迁移。
查看当前文件：
“`bash
ls -la
“`
一般可以看到：
“`text
.env
docker-compose.yml
data/
postgres_data/
redis_data/
“`
某些版本可能生成：
“`text
docker-compose.local.yml
“`
如果生成的是 `docker-compose.yml`，后面使用：
“`bash
docker compose up -d
“`
如果只生成了 `docker-compose.local.yml`，使用：
“`bash
docker compose -f docker-compose.local.yml up -d
“`
—
## 四、修改 Sub2API 基础配置
编辑 `.env`：
“`bash
nano /opt/sub2api-deploy/.env
“`
建议检查或修改以下配置：
“`env
BIND_HOST=127.0.0.1
SERVER_PORT=8080
SERVER_MODE=release
TZ=Asia/Tokyo
“`
其中：
“`env
BIND_HOST=127.0.0.1
“`
表示 Sub2API 的 8080 端口只监听本机，不直接暴露到公网，后面通过 Nginx 提供 HTTPS 服务。
如果是第一次启动，还可以提前设置管理员账号：
“`env
ADMIN_EMAIL=你的管理员邮箱
ADMIN_PASSWORD=一个足够复杂的密码
“`
如果 Sub2API 已经启动并创建了管理员账号，应登录后台修改密码，而不是只修改 `.env`。
启动服务：
“`bash
cd /opt/sub2api-deploy
docker compose up -d
“`
查看状态：
“`bash
docker compose ps
“`
查看日志：
“`bash
docker compose logs -f sub2api
“`
查找自动生成的管理员密码：
“`bash
docker compose logs sub2api \
| grep -Ei “admin password|管理员密码”
“`
访问：
“`text
http://服务器IP:8080
“`
默认管理员邮箱通常为：
“`text
admin@sub2api.local
“`
如果已经将 `BIND_HOST` 改成 `127.0.0.1`，公网将无法直接访问 8080，需要先完成后面的 Nginx 配置。
—
## 五、理解 IPRoyal 代理字符串
IPRoyal 提供的代理一般类似：
“`text
geo.iproyal.com:12321:USERNAME:PASSWORD_country-jp_session-Ab12Cd34_lifetime-168h
“`
从左到右分别是：
“`text
代理服务器：geo.iproyal.com
代理端口：12321
代理用户名：USERNAME
代理密码：PASSWORD_country-jp_session-Ab12Cd34_lifetime-168h
“`
特别注意：
“`text
_country-jp
“`
表示选择日本出口。
“`text
_session-Ab12Cd34
“`
表示创建粘性会话。IPRoyal 要求 session 值是正好 8 位的随机字母或数字。
“`text
_lifetime-168h
“`
表示该粘性会话最长保持 168 小时，也就是 7 天。7 天是 IPRoyal 当前粘性住宅代理会话的最长时间；到期后出口 IP 可能发生变化。
如果需要数周或数月保持同一个出口 IP，应购买静态住宅代理或 ISP 代理，而不是依赖轮换住宅代理的粘性会话。
—
## 六、先在 AWS 服务器上测试住宅代理
不要直接把真实密码写进命令历史。
输入代理用户名：
“`bash
read -rp “IPRoyal username: ” IPR_USER
“`
输入代理密码，输入内容不会显示：
“`bash
read -rsp “IPRoyal password: ” IPR_PASS
echo
“`
测试出口 IP：
“`bash
curl \
–fail \
–silent \
–show-error \
–connect-timeout 15 \
–max-time 30 \
–proxy “http://geo.iproyal.com:12321” \
–proxy-user “${IPR_USER}:${IPR_PASS}” \
https://ipinfo.io/json
“`
正常情况下会返回类似：
“`json
{
“ip”: “住宅代理出口IP”,
“country”: “JP”,
“region”: “Tokyo”
}
“`
测试完成后清除变量：
“`bash
unset IPR_USER
unset IPR_PASS
“`
如果返回：
“`text
407 Proxy Authentication Required
“`
通常是用户名或密码拆分错误。IPRoyal 的国家、session 和 lifetime 参数一般属于密码的一部分，不能漏掉。IPRoyal 官方示例同样将 `_country`、`_session` 和 `_lifetime` 参数放在密码字段中。
—
## 七、在 Sub2API 中添加住宅代理
登录 Sub2API 管理后台，找到：
“`text
代理管理
“`
不同版本的菜单名称可能略有区别，例如：
“`text
代理
代理池
IP 管理
Proxy Management
“`
点击新增代理。
### 情况一：后台使用分开的字段
填写：
“`text
名称：IPRoyal-JP-01
协议：HTTP
服务器：geo.iproyal.com
端口：12321
用户名：YOUR_USERNAME
密码：YOUR_PASSWORD_country-jp_session-Ab12Cd34_lifetime-168h
“`
这里协议建议选择：
“`text
HTTP
“`
即使访问的是 HTTPS 上游地址，也通常通过 HTTP 代理的 CONNECT 方法建立 HTTPS 隧道。
保存后点击：
“`text
测试代理
“`
确认测试结果显示日本住宅出口。
### 情况二：后台只有一个代理 URL 输入框
填写：
“`text
http://YOUR_USERNAME:YOUR_PASSWORD_country-jp_session-Ab12Cd34_lifetime-168h@geo.iproyal.com:12321
“`
不要把真实 URL 发布到博客、GitHub、截图或聊天群中。
如果用户名或密码包含以下特殊字符：
“`text
@
:
/
#
?
“`
需要先进行 URL 编码。为了减少编码问题，优先使用分开的服务器、端口、用户名和密码字段。
Sub2API 当前版本具有代理管理和账号代理绑定能力，代理通常需要在账号管理中逐个关联。
—
## 八、将代理绑定到上游账号
添加代理后，还需要将它绑定到具体的 Claude 或其他上游账号。
进入：
“`text
账号管理
“`
找到需要使用住宅出口的账号，点击：
“`text
编辑
“`
在代理选项中选择：
“`text
IPRoyal-JP-01
“`
保存后执行账号测试。
推荐顺序是：
“`text
1. 添加并测试代理
2. 创建或编辑上游账号
3. 给账号选择代理
4. 完成账号授权或重新授权
5. 执行账号连接测试
“`
不要只添加代理却不绑定账号。没有绑定代理的账号通常仍然会从 AWS 机房公网 IP 直接连接上游服务。
代理只会改变 Sub2API 向上游服务发送请求时的出口，不会改变以下流量的 IP：
“`text
浏览器登录 Sub2API 后台
本地 Claude Code 连接 Sub2API
浏览器进行第三方账号登录
AWS 控制台访问
SSH 登录服务器
“`
—
## 九、创建分组和 API Key
账号测试成功后，在 Sub2API 中创建一个分组，例如：
“`text
分组名称：Claude-Code
平台类型：Anthropic
“`
将刚才配置住宅代理的账号添加到该分组。
随后创建 API Key，例如：
“`text
sk-xxxxxxxxxxxxxxxx
“`
记录以下内容：
“`text
Sub2API 地址
API Key
可用模型名称
所属分组
“`
不要把管理员账号的 Token 当作 Claude Code 的 API Key 使用。
—
## 十、测试 Sub2API 接口
假设域名是：
“`text
https://cc.example.com
“`
设置临时变量：
“`bash
export ANTHROPIC_BASE_URL=”https://cc.example.com”
export ANTHROPIC_AUTH_TOKEN=”sk-替换为你的APIKey”
“`
发送测试请求：
“`bash
curl -sS \
“${ANTHROPIC_BASE_URL}/v1/messages” \
-H “x-api-key: ${ANTHROPIC_AUTH_TOKEN}” \
-H “anthropic-version: 2023-06-01” \
-H “content-type: application/json” \
-d ‘{
“model”: “替换为Sub2API中实际可用的模型名称”,
“max_tokens”: 64,
“messages”: [
{
“role”: “user”,
“content”: “只回复 OK”
}
]
}’
“`
如果返回正常内容，说明：
“`text
本地设备 → Sub2API
Sub2API → 账号代理
账号代理 → 上游服务
“`
整条链路基本正常。
—
## 十一、配置 Claude Code
在运行 Claude Code 的本地电脑中配置：
“`bash
export ANTHROPIC_BASE_URL=”https://cc.example.com”
export ANTHROPIC_AUTH_TOKEN=”sk-替换为你的APIKey”
“`
然后启动：
“`bash
claude
“`
Sub2API 的标准 Anthropic 接口一般使用根地址：
“`text
https://cc.example.com
“`
Claude Code 会自动请求：
“`text
https://cc.example.com/v1/messages
“`
社区实际配置中也使用 `ANTHROPIC_BASE_URL=http://服务器地址:端口` 连接 Sub2API。
如果使用的是 Sub2API 的 Antigravity 专用分组，则地址需要添加：
“`text
/antigravity
“`
例如：
“`bash
export ANTHROPIC_BASE_URL=”https://cc.example.com/antigravity”
export ANTHROPIC_AUTH_TOKEN=”sk-替换为你的APIKey”
“`
这是 Sub2API 官方仓库提供的 Antigravity Claude Code 配置方式。
临时测试成功后，可以将环境变量加入当前 Shell 配置文件，但需要注意文件中会保存明文 API Key：
“`bash
nano ~/.bashrc
“`
加入：
“`bash
export ANTHROPIC_BASE_URL=”https://cc.example.com”
export ANTHROPIC_AUTH_TOKEN=”sk-替换为你的APIKey”
“`
重新加载：
“`bash
source ~/.bashrc
“`
也可以通过 Claude Code 的 `settings.json` 配置环境变量。Claude Code 官方文档说明，网络和环境变量配置可以写入 `settings.json`。
—
## 十二、配置 Nginx 和 HTTPS
生产环境不建议通过：
“`text
http://服务器IP:8080
“`
直接访问 Sub2API。
先准备一个域名，例如：
“`text
cc.example.com
“`
在 DNS 中添加：
“`text
A 记录 → AWS EC2 弹性公网 IP
“`
安装 Nginx 和 Certbot：
“`bash
apt update
apt install -y nginx certbot python3-certbot-nginx
“`
创建配置：
“`bash
nano /etc/nginx/sites-available/sub2api
“`
填写：
“`nginx
server {
listen 80;
listen [::]:80;
server_name cc.example.com;
client_max_body_size 100m;
location / {
proxy_pass http://127.0.0.1:8080;
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;
proxy_buffering off;
proxy_request_buffering off;
proxy_connect_timeout 60s;
proxy_send_timeout 3600s;
proxy_read_timeout 3600s;
}
}
“`
启用站点：
“`bash
ln -s /etc/nginx/sites-available/sub2api \
/etc/nginx/sites-enabled/sub2api
“`
检查配置：
“`bash
nginx -t
“`
重新加载 Nginx：
“`bash
systemctl reload nginx
“`
申请 HTTPS 证书：
“`bash
certbot –nginx -d cc.example.com
“`
完成后访问：
“`text
https://cc.example.com
“`
确认 HTTPS 正常后，在 AWS 安全组中删除 8080 公网入站规则。
同时检查 `.env`：
“`env
BIND_HOST=127.0.0.1
“`
重新创建容器：
“`bash
cd /opt/sub2api-deploy
docker compose up -d
“`
检查服务器监听状态：
“`bash
ss -ntlp | grep -E “80|443|8080”
“`
理想结果为：
“`text
80 Nginx 对公网监听
443 Nginx 对公网监听
8080 仅在 127.0.0.1 监听
“`
—
## 十三、验证请求是否经过代理
### 1. 在 Sub2API 后台测试代理
进入代理管理，点击：
“`text
测试
“`
确认：
“`text
状态正常
国家为 JP
出口不是 AWS 公网 IP
“`
### 2. 测试绑定的账号
进入账号管理，对已经绑定代理的账号执行：
“`text
测试账号
“`
### 3. 查看 Sub2API 日志
“`bash
cd /opt/sub2api-deploy
docker compose logs -f sub2api
“`
筛选代理或上游错误：
“`bash
docker compose logs sub2api \
| grep -Ei “proxy|upstream|timeout|connect|EOF|407|429|403”
“`
### 4. 查看容器状态
“`bash
docker compose ps
“`
### 5. 查看健康检查
“`bash
curl -sS http://127.0.0.1:8080/health
“`
—
## 十四、常见问题
### 1. 返回 407 Proxy Authentication Required
原因通常是：
“`text
用户名错误
密码错误
将国家和 session 参数放错字段
密码中的特殊字符没有 URL 编码
代理套餐已经失效
“`
IPRoyal 格式中，以下内容一般都属于密码：
“`text
PASSWORD_country-jp_session-Ab12Cd34_lifetime-168h
“`
—
### 2. 代理测试是日本，但一段时间后 IP 变化
IPRoyal 轮换住宅代理的粘性会话最长为 7 天。即使设置：
“`text
_lifetime-168h
“`
也不能保证超过 7 天后继续使用相同 IP。
需要长期固定 IP 时，应使用：
“`text
静态住宅代理
ISP 代理
固定出口 VPN
“`
—
### 3. curl 可以使用代理，但 Sub2API 账号测试失败
检查：
“`text
代理是否已经绑定到账号
账号是否重新保存
Sub2API 是否为较新版本
代理是否允许访问目标域名
代理是否支持 HTTPS CONNECT
住宅代理流量是否已经耗尽
“`
更新 Sub2API：
“`bash
cd /opt/sub2api-deploy
docker compose pull
docker compose up -d
“`
Sub2API 官方推荐通过 `pull` 和重新执行 `up -d` 更新 Docker 部署。
—
### 4. Claude Code 仍然访问官方地址
检查本地变量：
“`bash
echo “$ANTHROPIC_BASE_URL”
echo “$ANTHROPIC_AUTH_TOKEN”
“`
确认 Claude Code 是在设置变量后的同一个终端中启动：
“`bash
claude
“`
也可以临时在一条命令中启动：
“`bash
ANTHROPIC_BASE_URL=”https://cc.example.com” \
ANTHROPIC_AUTH_TOKEN=”sk-你的APIKey” \
claude
“`
—
### 5. Claude Code 经常中断或出现 EOF
可能原因：
“`text
住宅节点质量不稳定
代理节点发生切换
代理连接数不足
Nginx 超时时间太短
Sub2API 上游请求超时
账号自身被限流
“`
先确认 Nginx 已设置：
“`nginx
proxy_buffering off;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
“`
然后在 Sub2API 中更换代理 session，重新测试。
Sub2API 的公开问题记录中也有代理异常导致上游出现 EOF 或请求失败的情况，因此生产使用时需要准备稳定出口和故障切换方案。
—
### 6. 住宅代理消耗流量过快
不要在 Docker Compose 中给整个 Sub2API 容器设置全局：
“`env
HTTP_PROXY=
HTTPS_PROXY=
“`
否则以下请求也可能经过住宅代理：
“`text
GitHub 更新检查
定价数据下载
其他平台请求
不需要代理的账号请求
“`
更合适的方法是：
“`text
在代理管理中添加代理
只给指定上游账号绑定代理
“`
Sub2API 的 `UPDATE_PROXY_URL` 只用于在线更新和定价数据，不是上游账号的统一代理配置。
—
## 十五、安全建议
不要直接对公网开放 8080。
不要在博客中发布：
“`text
IPRoyal 用户名
IPRoyal 密码
Sub2API 管理员密码
JWT_SECRET
TOTP_ENCRYPTION_KEY
PostgreSQL 密码
Claude Code API Key
OAuth Token
“`
建议：
“`text
使用 HTTPS
管理员开启双因素认证
AWS SSH 只允许自己的 IP
定期更新 Sub2API
定期备份数据库
限制 API Key 权限和额度
一个账号绑定一个稳定出口
避免突然提高并发量
“`
查看当前 `.env` 权限：
“`bash
chmod 600 /opt/sub2api-deploy/.env
“`
查看是否错误地将端口暴露到公网：
“`bash
ss -ntlp
“`
—
## 十六、日常维护命令
进入部署目录：
“`bash
cd /opt/sub2api-deploy
“`
查看状态：
“`bash
docker compose ps
“`
查看日志：
“`bash
docker compose logs -f sub2api
“`
重启 Sub2API：
“`bash
docker compose restart sub2api
“`
停止全部服务：
“`bash
docker compose down
“`
启动全部服务：
“`bash
docker compose up -d
“`
更新：
“`bash
docker compose pull
docker compose up -d
“`
不要随意执行：
“`bash
docker compose down -v
“`
也不要随意删除：
“`text
data/
postgres_data/
redis_data/
“`
否则可能导致账号、API Key、用户和使用记录丢失。
—
## 总结
最终配置完成后，请求链路为：
“`text
Claude Code
↓
HTTPS 域名
↓
Nginx
↓
Sub2API
↓
指定账号绑定的 IPRoyal 日本住宅代理
↓
上游模型服务
“`
关键点只有三个：
“`text
住宅代理添加到 Sub2API 的代理管理
住宅代理绑定到具体上游账号
Sub2API 的 8080 端口不直接暴露公网
“`
不需要给整台 AWS 服务器配置全局代理，也不需要让 PostgreSQL、Redis、Docker 等服务经过住宅代理。
评论(0)