服务公告
Drone - 常见问题 完全配置指南
发布时间:2026-04-29 16:01
一、前言
搞过Drone的人都知道，这玩意儿配置不难，但遇到问题时候日志看半天找不到原因。Runner不启动、构建卡死、webhook不触发——这几个坑我踩过无数次。今天把最常见的6个问题整理出来，都是实战中验证过的解法。
二、操作步骤
步骤1：检查Drone Agent连接状态
如果看到Runner一直显示offline，先确认网络和配置。
预期输出：
如果状态是inactive，检查配置文件是否正确。
步骤2：验证RPC连接配置
Runner和Server之间靠RPC通信，配置错一个字符都连不上。
预期输出：
⚠️ 警告：secret必须和Server端配置一致，字符对不上就永远连不上。
步骤3：排查构建卡在pending状态
构建状态一直是pending不动，说明没有可用的Runner或者Runner没连上Server。
预期输出：
如果所有Runner都是offline，回到步骤1和步骤2重新检查连接配置。
步骤4：处理Docker in Docker权限问题
Drone构建经常需要Docker in Docker，但经常遇到permission denied错误。
预期输出：
解法：把Runner进程用户加入docker组。
⚠️ 警告：如果是生产环境，考虑使用DinD或者kaniko等更安全的方案，不推荐简单粗暴加docker组。
步骤5：修复webhook触发不生效
Gitea/Gitea/Gogs仓库更新了但Drone没反应，先确认webhook配置。
如果返回403，说明webhook secret配置不匹配。
预期输出：
步骤6：解决SSL证书导致Runner无法注册
自签名证书环境下，Runner连Server会报证书验证失败。
预期输出：
⚠️ 警告：生产环境建议使用正式CA签发的证书，DRONE_RPC_SKIP_VERIFY=true仅限内网测试环境。
步骤7：清理卡住的构建任务
有时候构建因为网络或资源问题卡死，需要手动清理。
预期输出：
如果Runner一直处于busy状态但实际没有任务在跑，重启Runner服务。
三、常见问题FAQ
Q: Runner启动正常但一直offline，日志显示 "Dial tcp: i/o timeout"
这是网络不通的问题。先ping一下Server地址看能不能通，如果能ping通但还是超时，大概率是防火墙把8443端口或者RPC端口给拦了。在Runner机器上telnet your-drone-server 8443测试连通性。不通就逐个检查防火墙规则，服务端和客户端都要查。
Q: 构建过程中突然报错 "exec format error"
这个是架构不匹配。如果你用的是ARM Runner但镜像只支持amd64，或者反过来，就会报这个错。检查.pipeline里指定的镜像是否支持对应架构，或者在.drone.yml里用tags来指定不同Runner。
Q: 同一个仓库多个分支都触发了构建，但只想要PR和main分支构建
在仓库的Drone设置里配置分支过滤器，或者在.drone.yml里用条件判断。
直接在仓库页面的Settings → Build Settings →Branches里配置也行，更直观。
Q: 添加了新的Runner但构建还是只分配给旧的Runner
先drone runner ls看看新Runner状态是不是online。新Runner online后还需要等当前排队的任务结束才会分配。另外检查新旧Runner的标签是否冲突，有些pipeline指定了特定标签的Runner，新Runner标签不对就永远轮不到它。
四、总结
Drone的问题排查核心就几点：先看Runner状态确认连接，再查网络防火墙，最后看权限配置。遇到卡死的情况优先重启Runner服务，清理残留进程。自签名证书环境记得加DRONE_RPC_SKIP_VERIFY=true，但生产环境要用正规证书。
延伸阅读：
- Drone官方文档 - Runner配置：https://docs.drone.io/runner/overview/
- Drone配置参考 - .drone.yml完整语法：https://docs.drone.io/pipeline/overview/
相关推荐
已经是最后一篇啦！