综合新闻
Drone - 常见问题 完全配置指南
2026-04-29 16:01
Drone CI/CD 故障排查：6个常见问题实战解决指南
一、前言
搞过Drone的人都知道，这玩意儿配置不难，但遇到问题时候日志看半天找不到原因。Runner不启动、构建卡死、webhook不触发——这几个坑我踩过无数次。今天把最常见的6个问题整理出来，都是实战中验证过的解法。
二、操作步骤
步骤1：检查Drone Agent连接状态
如果看到Runner一直显示offline，先确认网络和配置。
# CentOS/RHEL 检查服务状态
systemctl status drone-runner
# Ubuntu 检查服务状态
sudo systemctl status drone-runner
# 查看详细日志
journalctl -u drone-runner -f
预期输出：
● drone-runner.service - Drone CI Runner
Loaded: loaded (/etc/systemd/system/drone-runner.service; enabled)
Active: active (running) since Mon 2024-01-15 10:30:00 CST; 2h ago
Main PID: 1234 (drone-runner)
如果状态是inactive，检查配置文件是否正确。
步骤2：验证RPC连接配置
Runner和Server之间靠RPC通信，配置错一个字符都连不上。
# 检查Drone Server地址配置
# CentOS/RHEL: /etc/drone-runner-drone/runner.env
# Ubuntu: /etc/drone-runner/runner.env
cat /etc/drone-runner/runner.env
预期输出：
DRONE_RPC_PROTO=https
DRONE_RPC_HOST=drone.example.com
DRONE_RPC_SECRET=YOUR_RPC_SECRET
DRONE_RUNNER_CAPACITY=2
DRONE_RUNNER_NAME=runner-01
⚠️ 警告：secret必须和Server端配置一致，字符对不上就永远连不上。
步骤3：排查构建卡在pending状态
构建状态一直是pending不动，说明没有可用的Runner或者Runner没连上Server。
# 在Drone Server上查看注册的所有Runner
drone runner ls
# 查看当前构建队列
drone build list --limit=5
预期输出：
NAME STATE CAPACITY LABELS
runner-01 online 2 linux,amd64
runner-02 online 1 linux,arm64
# 如果看到 State: offline，说明这个Runner挂了
如果所有Runner都是offline，回到步骤1和步骤2重新检查连接配置。
步骤4：处理Docker in Docker权限问题
Drone构建经常需要Docker in Docker，但经常遇到permission denied错误。
# 检查docker.sock权限
ls -la /var/run/docker.sock
# 应该看到类似这样的权限
srw-rw---- 1 root root 12345 Jan 15 10:30 /var/run/docker.sock
预期输出：
srw-rw---- 1 root docker Jan 15 10:30 /var/run/docker.sock
解法：把Runner进程用户加入docker组。
# CentOS/RHEL 和 Ubuntu 通用
usermod -aG docker drone-runner
# 重启Runner服务
systemctl restart drone-runner
⚠️ 警告：如果是生产环境，考虑使用DinD或者kaniko等更安全的方案，不推荐简单粗暴加docker组。
步骤5：修复webhook触发不生效
Gitea/Gitea/Gogs仓库更新了但Drone没反应，先确认webhook配置。
# 登录Gitea/Gitea后台，检查仓库设置中的Webhooks
# 确认URL指向: http://your-drone-server/drone/webhook
# 在仓库的 webhook 设置页面，点击 "Test Delivery" 手动触发
# 查看返回状态码是否为 200
如果返回403，说明webhook secret配置不匹配。
# 检查Drone Server的webhook secret配置
# DRONE_WEBHOOK_SECRET=your_secret
# 确保Gitea/Gitea仓库的webhook secret和这个一致
预期输出：
HTTP 200 OK - Delivery successful
步骤6：解决SSL证书导致Runner无法注册
自签名证书环境下，Runner连Server会报证书验证失败。
# 在Runner配置中添加跳过证书验证
# 编辑 runner.env 或 runner.conf
DRONE_RPC_SKIP_VERIFY=true
预期输出：
# 重启后Runner日志应该显示
INFO core: polling runner
INFO server: connected to drone server
⚠️ 警告：生产环境建议使用正式CA签发的证书，DRONE_RPC_SKIP_VERIFY=true仅限内网测试环境。
步骤7：清理卡住的构建任务
有时候构建因为网络或资源问题卡死，需要手动清理。
# 查看卡住的构建
drone build ls --status=killed
# 强制取消构建
drone build stop namespace/repo 123
# 查看当前运行中的构建
drone build ls --status=running
预期输出：
# 取消成功的输出
Build #123 stopped
如果Runner一直处于busy状态但实际没有任务在跑，重启Runner服务。
# CentOS/RHEL
systemctl restart drone-runner
# Ubuntu
sudo systemctl restart drone-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。
kind: pipeline
type: docker
node:
name: arm-runner
platform:
os: linux
arch: arm64
Q: 同一个仓库多个分支都触发了构建，但只想要PR和main分支构建
在仓库的Drone设置里配置分支过滤器，或者在.drone.yml里用条件判断。
trigger:
branch:
- main
- develop
event:
- pull_request
- push
直接在仓库页面的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，但生产环境要用正规证书。
延伸阅读：
`
content = content.indexOf('') > 0 ? content.replace('', viewstyle + '') : viewstyle + content
const iframe = document.querySelector('#viewcontent')
const viewdoc = iframe.contentDocument
viewdoc.open()
viewdoc.write(content)
viewdoc.close()
iframe.height = viewdoc.body.scrollHeight + 20
})
