ClawCloud 部署 Sub2API 记录 + 踩坑过程
- 内容介绍
- 文章标签
- 相关推荐
最近在 ClawCloud 上部署了一下 sub2api，中间踩了几个坑，最后跑通了。 发个记录，给后面遇到同样问题的人参考。
先准备一个clawcloud账号+redis+PostgreSQL，如果没有redis和PostgreSQL自己部署一个
redis我用的upstash
部署
1.创建APP
镜像填入
weishaw/sub2api:latest
image-202603082335251071330×780 51.4 KB
2.网络 端口改成8080 或者自己的域名 设置一个CNAME解析即可
image-20260308233635966840×259 16.7 KB
3.其他的不用管，默认即可。 设置环境变量
image-20260308233907118924×434 26.9 KB
image-20260308233920924553×366 15.5 KB
直接贴最终可用配置：
AUTO_SETUP=true
SERVER_HOST=0.0.0.0
SERVER_PORT=8080
SERVER_MODE=release
RUN_MODE=standard
TZ=Asia/Shanghai
DATABASE_HOST=tcp.us-west-1.clawcloudrun.com
DATABASE_PORT=38794
DATABASE_USER=postgres
DATABASE_PASSWORD=你的数据库密码
DATABASE_DBNAME=sub2api
DATABASE_SSLMODE=disable
REDIS_HOST=你的redis地址
REDIS_PORT=6379
REDIS_PASSWORD=你的redis密码
REDIS_ENABLE_TLS=true
ADMIN_EMAIL=你的邮箱
ADMIN_PASSWORD=你的后台密码
JWT_SECRET=0123456789abcdef0123456789abcdef01234567
TOTP_ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
重点说两个字段
1）TOTP_ENCRYPTION_KEY
这个必须是：
64 位十六进制字符串也就是 32 bytes只能是 0-9 a-f
例如：
TOTP_ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
如果长度不对，程序会直接启动失败。
2）JWT_SECRET
这个随便你自己换，但别写得太奇怪，先用纯字母数字比较省事。
4.硬盘挂载
/app/data
image-202603090014571721000×170 9.86 KB
最终效果
image-20260309001610518739×781 51.6 KB
5.回到顶部开始部署即可 等一下就ok了
image-202603082343217631858×726 53 KB
踩坑：
1.TOTP_ENCRYPTION_KEY 长度不对，服务直接起不来
Failed to initialize application: totp encryption key must be 32 bytes (64 hex chars), got 20 bytes
我这里最关键的问题其实不是数据库，也不是 Redis，真正卡住启动的是这个变量。
日志会直接报：
Failed to initialize application: totp encryption key must be 32 bytes (64 hex chars), got 20 bytes
一开始我以为自己已经改对了，结果容器实际读到的还是旧值。 这个变量要求很死：
- 必须是 64 个十六进制字符
- 也就是 32 bytes
- 只能是 0-9 和 a-f
像下面这种才是对的：
TOTP_ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
这个坑最烦的地方在于： 你以为自己改了，不代表程序真的读到了新值。
2、改了环境变量后，光重启不一定有用
我这里还有个误区： 以为改完环境变量，点一下 Restart 就好了
实际上有的平台只是把旧容器重新拉起来，不一定把最新环境变量完整带进去。 所以如果你已经改了配置，但日志还是报一样的错，不要怀疑人生，先确认：
- 配置是不是保存成功了
- 是不是重新部署了
- 旧实例是不是还在吃老环境变量
我后面是直接删掉重来
3、管理员密码不是你改了环境变量就会跟着变
这个也很容易误判。
我当时登录页一直提示：
invalid email or password
但我明明把：
ADMIN_EMAIL=xxx
ADMIN_PASSWORD=xxx
都写上了。
后来看日志才发现有这句：
Admin user already exists, skipping admin bootstrap
这句话的意思很直接：
- 数据库里已经存在管理员账号
- 应用不会再用新的 ADMIN_PASSWORD 去覆盖旧密码
也就是说，ADMIN_PASSWORD 更像是首次初始化时生效。 如果数据库里已经有 admin 了，你后面再改环境变量是没用的。
我最后是因为本来就是测试环境，干脆把数据库删了重建，重新初始化后就正常登录了。
4、登录失败的时候，未必是你现在这套账号密码错了
这个跟上面那个问题是连着的。
因为数据库里如果已经有旧 admin，登录时真正生效的是数据库里的旧密码，不是你环境变量里后来新写的那个。 所以遇到登录失败，不要只盯着页面上的 invalid email or password，还要去看启动日志里有没有：
Admin user already exists, skipping admin bootstrap
如果有，那基本就说明不是前端问题，是初始化逻辑的问题。
5、/app/data/logs: permission denied
我还看到过这个报错：
mkdir /app/data/logs: permission denied
刚看到的时候我以为就是它导致容器起不来，后来实际排下来发现，它不是我这边的核心问题。 真正导致启动失败的，还是 TOTP_ENCRYPTION_KEY 的长度问题。
所以建议看日志的时候，先分清：
- 哪些是 fatal
- 哪些只是 warning
- 哪些只是附带报错
不然很容易被权限问题带偏，结果越排越远。
6、数据库和 Redis 通了，不代表应用一定能启动
这个也是我一开始的误区。
因为日志里其实已经显示过类似：
Database connection successful
Redis connection successful
看到这里我就默认后面应该没啥问题了，结果还是起不来。 后来才知道，连接成功只代表依赖服务没问题，不代表应用配置完整无误。
像这种场景里：
- DB 正常
- Redis 正常
- 但关键安全配置不合法
应用一样会直接退出。
7、安装向导页面循环
image-202603090005552081024×866 77.2 KB
image-202603090004315011054×844 57.9 KB
重启之后一打开就又开始这个
image-202603090005552081024×866 77.2 KB
那就是环境变量错了，没读到，直接copy我的模板
8.最大的坑：
晚上折腾服务器
总结：最省时间的办法，有时候不是修，而是重建
部署PostgreSQL参考：
镜像
postgres:15.17
端口 5432 记得改成tcp
image-20260309001226438740×186 13.1 KB
配置模板：
POSTGRES_USER=postgres
POSTGRES_PASSWORD=密码
POSTGRES_DB=sub2api
PGDATA=/var/lib/postgresql/data/pgdata
硬盘挂载
/var/lib/postgresql/data
--【壹】--：
我两天前的自定义域名现在还没解析好
--【贰】--：
数据卷是什么，我在上面搞了一个opencalw,我给他配置完之后重启就没了
--【叁】--：
感谢佬分享，很详细了
--【肆】--：
强呀，大佬
--【伍】--：
这方法有说法，马上去试试
--【陆】--：
感谢佬分享经验！
--【柒】--：
修起来确实更麻烦
--【捌】--：
大佬，搭好以后全国延迟怎么样？
--【玖】--：
学会了，膜拜大佬
--【拾】--：
据说sub2api快一些 这个你得自己测 我部署在不同环境 不好对比
--【拾壹】--：
可能是区域 我一开始在jp部署的 一直不生效 在美西秒好
如果自定义的话你先试试 新加一条同端口的 然后把老的删了
--【拾贰】--：
爪云重启之后是不是数据都没了
--【拾叁】--：
這東西 (ClawCloud Run) 之前弄得我覺得很噁心。
珍惜生命，遠離 ClawCloud Run。
--【拾肆】--：
每个GET/SET/INCR都算1个，不是按请求次数
--【拾伍】--： Charles:
爪云重启之后是不是数据都没了
挂载了数据卷的就还在
--【拾陆】--：
upstash 的redis用了两周 commond干到了95万直接超出免费计划了，这合理吗
--【拾柒】--：
爽啊，还得是正规军，这不比自己折腾VPS快多了，另外想问问我在用CPA如果不是为了给别人计费分享的话，有必要换成sub2api吗
--【拾捌】--：
感谢大佬分享
--【拾玖】--：
延迟有一些 主要看你地区吧 你开了pro基本上就没什么延迟
87b759c5b4eef12dda8f06714dec39b0461×539 18.7 KB
最近在 ClawCloud 上部署了一下 sub2api，中间踩了几个坑，最后跑通了。 发个记录，给后面遇到同样问题的人参考。
先准备一个clawcloud账号+redis+PostgreSQL，如果没有redis和PostgreSQL自己部署一个
redis我用的upstash
部署
1.创建APP
镜像填入
weishaw/sub2api:latest
image-202603082335251071330×780 51.4 KB
2.网络 端口改成8080 或者自己的域名 设置一个CNAME解析即可
image-20260308233635966840×259 16.7 KB
3.其他的不用管，默认即可。 设置环境变量
image-20260308233907118924×434 26.9 KB
image-20260308233920924553×366 15.5 KB
直接贴最终可用配置：
AUTO_SETUP=true
SERVER_HOST=0.0.0.0
SERVER_PORT=8080
SERVER_MODE=release
RUN_MODE=standard
TZ=Asia/Shanghai
DATABASE_HOST=tcp.us-west-1.clawcloudrun.com
DATABASE_PORT=38794
DATABASE_USER=postgres
DATABASE_PASSWORD=你的数据库密码
DATABASE_DBNAME=sub2api
DATABASE_SSLMODE=disable
REDIS_HOST=你的redis地址
REDIS_PORT=6379
REDIS_PASSWORD=你的redis密码
REDIS_ENABLE_TLS=true
ADMIN_EMAIL=你的邮箱
ADMIN_PASSWORD=你的后台密码
JWT_SECRET=0123456789abcdef0123456789abcdef01234567
TOTP_ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
重点说两个字段
1）TOTP_ENCRYPTION_KEY
这个必须是：
64 位十六进制字符串也就是 32 bytes只能是 0-9 a-f
例如：
TOTP_ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
如果长度不对，程序会直接启动失败。
2）JWT_SECRET
这个随便你自己换，但别写得太奇怪，先用纯字母数字比较省事。
4.硬盘挂载
/app/data
image-202603090014571721000×170 9.86 KB
最终效果
image-20260309001610518739×781 51.6 KB
5.回到顶部开始部署即可 等一下就ok了
image-202603082343217631858×726 53 KB
踩坑：
1.TOTP_ENCRYPTION_KEY 长度不对，服务直接起不来
Failed to initialize application: totp encryption key must be 32 bytes (64 hex chars), got 20 bytes
我这里最关键的问题其实不是数据库，也不是 Redis，真正卡住启动的是这个变量。
日志会直接报：
Failed to initialize application: totp encryption key must be 32 bytes (64 hex chars), got 20 bytes
一开始我以为自己已经改对了，结果容器实际读到的还是旧值。 这个变量要求很死：
- 必须是 64 个十六进制字符
- 也就是 32 bytes
- 只能是 0-9 和 a-f
像下面这种才是对的：
TOTP_ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
这个坑最烦的地方在于： 你以为自己改了，不代表程序真的读到了新值。
2、改了环境变量后，光重启不一定有用
我这里还有个误区： 以为改完环境变量，点一下 Restart 就好了
实际上有的平台只是把旧容器重新拉起来，不一定把最新环境变量完整带进去。 所以如果你已经改了配置，但日志还是报一样的错，不要怀疑人生，先确认：
- 配置是不是保存成功了
- 是不是重新部署了
- 旧实例是不是还在吃老环境变量
我后面是直接删掉重来
3、管理员密码不是你改了环境变量就会跟着变
这个也很容易误判。
我当时登录页一直提示：
invalid email or password
但我明明把：
ADMIN_EMAIL=xxx
ADMIN_PASSWORD=xxx
都写上了。
后来看日志才发现有这句：
Admin user already exists, skipping admin bootstrap
这句话的意思很直接：
- 数据库里已经存在管理员账号
- 应用不会再用新的 ADMIN_PASSWORD 去覆盖旧密码
也就是说，ADMIN_PASSWORD 更像是首次初始化时生效。 如果数据库里已经有 admin 了，你后面再改环境变量是没用的。
我最后是因为本来就是测试环境，干脆把数据库删了重建，重新初始化后就正常登录了。
4、登录失败的时候，未必是你现在这套账号密码错了
这个跟上面那个问题是连着的。
因为数据库里如果已经有旧 admin，登录时真正生效的是数据库里的旧密码，不是你环境变量里后来新写的那个。 所以遇到登录失败，不要只盯着页面上的 invalid email or password，还要去看启动日志里有没有：
Admin user already exists, skipping admin bootstrap
如果有，那基本就说明不是前端问题，是初始化逻辑的问题。
5、/app/data/logs: permission denied
我还看到过这个报错：
mkdir /app/data/logs: permission denied
刚看到的时候我以为就是它导致容器起不来，后来实际排下来发现，它不是我这边的核心问题。 真正导致启动失败的，还是 TOTP_ENCRYPTION_KEY 的长度问题。
所以建议看日志的时候，先分清：
- 哪些是 fatal
- 哪些只是 warning
- 哪些只是附带报错
不然很容易被权限问题带偏，结果越排越远。
6、数据库和 Redis 通了，不代表应用一定能启动
这个也是我一开始的误区。
因为日志里其实已经显示过类似：
Database connection successful
Redis connection successful
看到这里我就默认后面应该没啥问题了，结果还是起不来。 后来才知道，连接成功只代表依赖服务没问题，不代表应用配置完整无误。
像这种场景里：
- DB 正常
- Redis 正常
- 但关键安全配置不合法
应用一样会直接退出。
7、安装向导页面循环
image-202603090005552081024×866 77.2 KB
image-202603090004315011054×844 57.9 KB
重启之后一打开就又开始这个
image-202603090005552081024×866 77.2 KB
那就是环境变量错了，没读到，直接copy我的模板
8.最大的坑：
晚上折腾服务器
总结：最省时间的办法，有时候不是修，而是重建
部署PostgreSQL参考：
镜像
postgres:15.17
端口 5432 记得改成tcp
image-20260309001226438740×186 13.1 KB
配置模板：
POSTGRES_USER=postgres
POSTGRES_PASSWORD=密码
POSTGRES_DB=sub2api
PGDATA=/var/lib/postgresql/data/pgdata
硬盘挂载
/var/lib/postgresql/data
--【壹】--：
我两天前的自定义域名现在还没解析好
--【贰】--：
数据卷是什么，我在上面搞了一个opencalw,我给他配置完之后重启就没了
--【叁】--：
感谢佬分享，很详细了
--【肆】--：
强呀，大佬
--【伍】--：
这方法有说法，马上去试试
--【陆】--：
感谢佬分享经验！
--【柒】--：
修起来确实更麻烦
--【捌】--：
大佬，搭好以后全国延迟怎么样？
--【玖】--：
学会了，膜拜大佬
--【拾】--：
据说sub2api快一些 这个你得自己测 我部署在不同环境 不好对比
--【拾壹】--：
可能是区域 我一开始在jp部署的 一直不生效 在美西秒好
如果自定义的话你先试试 新加一条同端口的 然后把老的删了
--【拾贰】--：
爪云重启之后是不是数据都没了
--【拾叁】--：
這東西 (ClawCloud Run) 之前弄得我覺得很噁心。
珍惜生命，遠離 ClawCloud Run。
--【拾肆】--：
每个GET/SET/INCR都算1个，不是按请求次数
--【拾伍】--： Charles:
爪云重启之后是不是数据都没了
挂载了数据卷的就还在
--【拾陆】--：
upstash 的redis用了两周 commond干到了95万直接超出免费计划了，这合理吗
--【拾柒】--：
爽啊，还得是正规军，这不比自己折腾VPS快多了，另外想问问我在用CPA如果不是为了给别人计费分享的话，有必要换成sub2api吗
--【拾捌】--：
感谢大佬分享
--【拾玖】--：
延迟有一些 主要看你地区吧 你开了pro基本上就没什么延迟
87b759c5b4eef12dda8f06714dec39b0461×539 18.7 KB