v1.0.0-migration-guide.zh-CN.md

English | 简体中文

Resin v1.0.0 迁移指南（Auth 版本切换）

本文面向从旧版本升级到 v1.0.0 的用户，目标是平滑完成认证格式迁移，避免启动失败或请求认证失败。

1. 先保证服务可启动（兼容模式）

v1.0.0 开始，必须配置环境变量 RESIN_AUTH_VERSION。

如果你是从旧版本直接升级，推荐第一步先用兼容模式启动：

RESIN_AUTH_VERSION=LEGACY_V0

这样可先保持旧认证行为不变，服务先恢复可用，再进行后续迁移。

2. 清理不兼容配置

2.1 检查并修正 RESIN_PROXY_TOKEN

切换到 V1 前，RESIN_PROXY_TOKEN 不能包含以下字符：

• .:|/\@?#%~
• 空格、tab、换行、回车

2.2 检查并修正 Platform 名称

切换到 V1 前，请检查您的 Platform 名称。不能：

• 包含 .:|/\@?#%~
• 包含空格、tab、换行、回车
• 等于保留字

如存在历史不合规平台名，请在 LEGACY_V0 下先重命名，再切换到 V1。

3. 切换到 V1

完成以上清理后，将环境变量改为：

RESIN_AUTH_VERSION=V1

重启后，如果有不兼容项，服务会拒绝启动并给出错误提示。

4. 客户端认证格式变更

正向代理（Forward Proxy）

• 旧格式（LEGACY_V0）：RESIN_PROXY_TOKEN:Platform:Account
• 新格式（V1）：Platform.Account:RESIN_PROXY_TOKEN

curl 示例（V1）：

curl -x http://127.0.0.1:2260 \
  -U "Default.user_tom:my-token" \
  https://api.ipify.org

反向代理（Reverse Proxy）

• 旧格式（LEGACY_V0）：/token/Platform:Account/protocol/host/path
• 新格式（V1）：/token/Platform.Account/protocol/host/path，或者使用 X-Resin-Account 请求头来提供 Account。

curl 示例（V1）：

# URL 中提供 Account
curl "http://127.0.0.1:2260/my-token/Default.user_tom/https/api.ipify.org"

# 通过 X-Resin-Account 请求头提供 Account
curl "http://127.0.0.1:2260/my-token/Default/https/api.ipify.org" -H "X-Resin-Account: user_tom"