Woodpecker CI Agent容器启动失败问题分析与解决方案

问题现象

在使用Docker部署Woodpecker CI服务时，用户遇到了Agent容器无法正常启动的问题。从日志中可以观察到，服务器容器能够正常启动，但Agent容器反复尝试启动失败，并报出"AgentID not found in database"的错误信息。

错误分析

日志中显示的关键错误信息是：

rpc error: code = Unknown desc = agent could not auth: AgentID not found in database

这表明Agent容器在尝试与服务器建立认证连接时，服务器端无法在数据库中查找到对应的Agent ID记录。这种情况通常发生在Agent与服务器之间的认证信息不匹配或配置不正确时。

可能的原因

1. 认证令牌配置错误：Agent使用的Secret与服务器端配置不匹配
2. 数据库同步问题：服务器未能正确将Agent信息写入数据库
3. 配置残留：系统中可能存在旧的Agent配置文件干扰了新配置
4. 启动顺序问题：Agent容器可能在服务器完全初始化前就开始尝试连接

解决方案

方案一：使用正确的Agent Token

确保使用的是专门为Agent生成的Token，而不是系统Token。正确的做法是：

1. 通过Woodpecker服务器管理界面生成专用的Agent Token
2. 在Agent配置中使用这个Token作为认证凭据

方案二：手动注册Agent

当自动注册失败时，可以尝试手动注册Agent：

1. 登录Woodpecker服务器管理界面
2. 进入Agent管理部分
3. 手动添加一个新的Agent记录
4. 确保Agent配置中使用与服务器端匹配的ID和Token

方案三：检查配置一致性

1. 验证服务器和Agent的环境变量配置是否一致
2. 检查是否有旧的配置文件残留，特别是/etc/woodpecker/目录下的文件
3. 确保所有容器使用相同版本的Woodpecker组件

最佳实践建议

1. 部署顺序：确保服务器容器完全启动并初始化完成后再启动Agent容器
2. 日志监控：部署后密切监控服务器和Agent的日志输出
3. 版本一致性：保持服务器和Agent组件版本一致
4. 配置验证：部署前验证所有环境变量和配置文件

总结

Woodpecker CI的Agent启动失败问题通常与认证配置相关。通过正确配置Agent Token、确保数据库同步以及必要时手动注册Agent，可以有效解决这类问题。对于生产环境部署，建议建立完善的监控机制，以便及时发现和解决类似问题。