布署采坑大全

布署踩坑记录

数据迁移

环境配置好的后，准备初始化数据库

sudo bash -lc 'set -a; source /etc/cycle-scheduler/.env; set +a; /opt/cycle-scheduler/bin/cycle-migrate'

初始化用户

sudo bash -lc 'set -a; source /etc/cycle-scheduler/.env; set +a; /opt/cycle-scheduler/bin/cycle-initadmin'

进程启动后，进程报错一直重启

查看报错日志

sudo systemctl stop cycle-api
sudo journalctl -u cycle-api -b --no-pager -n 300

持续跟踪日志

sudo journalctl -u cycle-api -f

查看端口是否被占用

sudo lsof -nP -iTCP:8080 -sTCP:LISTEN

不用 systemctl 启动，直接用环境变量通过命令行启动

sudo bash -lc 'set -a; source /etc/cycle-scheduler/.env; set +a; /opt/cycle-scheduler/bin/cycle-api'

程序无法启动

检查 bin 文件目录的权限，用户组是否为 cycle, 因为 systemd 配置文件中指定了进程启动的用户，用户组是 cycle，bin 文件需要 cycle 用户可读。

如果还没有添加 cycle 用户，则需要先创建 cycle 用户;

sudo adduser --system --group --home /opt/cycle-scheduler --shell /usr/sbin/nologin cycle

将 opt/cycle-scheduler 目录权限给 cycle:cycle 用户

chown -R cycle:cycle /opt/cycle-scheduler

scheduler 进程报错

这个是因为数据库版本问题，项目使用了 MySQL 8 的特性，在 MySQL 5.7 不兼容；需要调整代码，检测 MySQL 版本，做功能适配。

Feb 10 15:59:44 iZ2vc1e7i33nss0hxozpu2Z cycle-scheduler[4109874]: {"time":"2026-02-10T15:59:44.019671759+08:00","level":"ERROR","msg":"lease sweep failed","err":"Error 1064 (42000): You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'SKIP LOCKED' at line 14"}

agent 进程启动后持续报错

err: register failed: status=401; 是因为 CYCLE_AGENT_AUTH_TOKEN 配置不对，或CYCLE_AGENT_API_URL 不对；

检查环境配置文件，添加一个 CYCLE_AGENT_AUTH_TOKEN 和 CYCLE_AUTH_ADMIN_TOKEN, 将两个 token 配置成一样的随机字符串。再重启 cycle-api, cycle-agent。

agent 创建 worker 报错

{"time":"2026-02-10T17:07:31.631022391+08:00","level":"WARN","msg":"start worker failed","tenantId":1,"err":"build worker failed: exec: \"go\": executable file not found in $PATH"}

是因为环境变量里没有配置 cycle-worker 的文件位置，agent 找不到文件，所以偿试去找 go 编译。

只需要在 .env 文件中添加，CYCLE_AGENT_WORKER_EXEC ，然后: systemctl restart cycle-agent 即可。

CYCLE_AGENT_WORKER_EXEC=/opt/cycle-scheduler/bin/cycle-worker