---
name: deploy
description: Drone CI + 服务器 CD 全流程引导：从基础设施检查到生成配置文件到验证部署，交互式完成。
---

# Deploy - CI/CD 全流程部署引导

> **定位**：基于公司 Drone CI + 私有 Docker Registry + Docker Compose 的自动化部署方案，交互式引导用户从零完成 CI/CD 接入。

当用户调用 `/deploy` 或 `/deploy <指令>` 时，执行以下步骤：

## 1. 收集项目信息

快速了解项目情况（已知的不重复问）：

| 项目 | 说明 | 示例 |
|------|------|------|
| 项目名称 | 用于镜像命名 | `douyin`, `crm`, `blog` |
| 需构建的服务 | 每个服务对应一个镜像 | `backend`, `frontend` |
| 各服务的 Dockerfile 路径 | Docker build context | `./backend`, `./frontend` |
| 生产服务器 SSH 端口 | 默认 22 | `22`, `3141` |
| 部署目录 | 生产服务器上的路径 | `/opt/docker/myproject` |
| 数据库迁移命令 | 如有 | `alembic upgrade head`, `npx prisma migrate deploy` |
| 健康检查方式 | 三选一 | python / curl / host |
| 健康检查 URL | 容器内地址 | `http://127.0.0.1:8000/health` |
| 通知 Webhook | 可选，不配则跳过 | 企业微信/钉钉/飞书 |

确认后进入下一步。

## 2. 基础设施检查

输出 Checklist，让用户逐项确认（首次接入需全部完成，后续项目可跳过）：

```
□ 基础设施（一次性，已完成则跳过）
  □ Drone CI Server + Runner 已部署运行
  □ 私有 Docker Registry 已运行（默认 :5000）
  □ insecure-registries 已配置（Drone CI 服务器 + 生产服务器）
  □ SSH 密钥已配置（Drone CI 服务器 → 生产服务器免密登录）
  □ 生产服务器用户已加入 docker 组
```

如果用户表示基础设施未就绪，输出对应的一次性搭建指引（参见下方「附录：基础设施搭建」）。

## 3. 生成配置文件

基于收集到的信息，生成以下文件：

### 3.1 `.drone.yml`

核心原则（踩坑总结，不可违反）：
1. 使用 `docker:27-cli` + 宿主机 Docker socket，**不用** `plugins/docker` DinD
2. 使用 `environment: { VAR: { from_secret: name } }` 注入密钥，**不用** `secrets:` 字段
3. 使用 `${DRONE_TAG:-latest}` 作为镜像 tag，**不自定义中间变量**（Drone 变量替换冲突）
4. 触发条件只用 `event: [tag, cron]`，**不叠加** `cron: [name]`（AND 运算陷阱）

生成内容包括：
- `trigger`: tag + cron
- `volumes`: 挂载宿主机 Docker socket
- 每个服务的 `build-<service>` step
- `deploy` step（使用 `appleboy/drone-ssh`）
- `notify-success` / `notify-failure` step（如配置了 Webhook）

### 3.2 `scripts/deploy-remote.sh`

部署脚本要点：
- `set -euo pipefail` 严格模式
- 部署锁（PID 文件防并发）
- 同时 export `IMAGE_TAG` 和 `VERSION`（兼容不同 compose 变量命名）
- 按顺序：pull → 停 beat → 更新核心服务 → 健康检查 → 数据库迁移 → 启动剩余服务 → 最终健康检查
- 健康检查根据用户选择的方式生成（python / curl / host）

### 3.3 生成后展示

```
已生成：
  📄 .drone.yml                    — Drone CI 流水线配置
  📄 scripts/deploy-remote.sh      — 远程部署脚本

确认写入？[Y/n]
```

用户确认后写入文件。

## 4. Drone 面板配置引导

生成文件后，输出需要在 Drone 面板手动配置的清单：

### 4.1 仓库设置

```
在 Drone 面板完成以下配置：

1. 激活仓库：SYNC → 找到仓库 → ACTIVATE
2. 开启 Trusted：Settings → General → Project Settings → 勾选 Trusted
```

### 4.2 Secrets 配置

根据收集到的信息，输出具体的 Secret 列表：

```
在 Drone 面板 → 仓库 Settings → Secrets 添加：

| Secret 名称      | 填写内容                                           |
|-------------------|----------------------------------------------------|
| backend_repo      | docker.internal.intelligrow.cn:5000/{project}-backend  |
| frontend_repo     | docker.internal.intelligrow.cn:5000/{project}-frontend |
| deploy_host       | {生产服务器 IP}                                    |
| deploy_user       | {SSH 用户}                                         |
| deploy_ssh_key    | cat ~/.ssh/drone_deploy 的完整内容                 |
| deploy_path       | {部署目录}                                         |
| wecom_webhook     | {Webhook URL}（如已配置）                          |
```

### 4.3 Cron 配置（可选）

```
如需定时构建，在 Settings → Cron Jobs 添加：

| 字段     | 值               | 说明                    |
|----------|------------------|-------------------------|
| Name     | nightly-build    | 任务名称                |
| Branch   | main             | 构建分支                |
| Schedule | 0 16 * * *       | UTC 16:00 = 北京 00:00  |
```

## 5. 生产服务器配置引导

```
在生产服务器上确认：

1. 部署目录结构：
   {deploy_path}/
   ├── docker-compose.prod.yml
   ├── .env
   └── scripts/
       └── deploy-remote.sh    ← 需从代码仓库复制

2. .env 至少包含：
   DOCKER_REGISTRY=docker.internal.intelligrow.cn:5000
   （其他数据库密码等生产配置）

3. docker-compose.prod.yml 中镜像引用格式：
   image: ${DOCKER_REGISTRY}/{project}-backend:${VERSION:-latest}

⚠️ 变量一致性：Drone Secret 的镜像地址前缀 = .env 的 DOCKER_REGISTRY = compose 中的镜像名拼接结果
```

## 6. 验证

自己执行可执行的验证，不能远程执行的给出命令让用户确认结果：

### 6.1 本地验证（自己执行）

```bash
# 检查 .drone.yml 语法合法性（YAML 解析）
# 检查 deploy-remote.sh 语法（bash -n）
# 检查文件是否已正确写入
```

### 6.2 远程验证引导（输出命令，让用户在服务器上执行并反馈结果）

```bash
# 推送 Tag 触发首次构建
git tag v{version}
git push origin v{version}

# 观察 Drone 面板 pipeline 状态

# 生产服务器检查
ssh -p {port} {user}@{host} "cd {deploy_path} && docker compose -f docker-compose.prod.yml ps"
```

## 7. 完成输出

```
✅ CI/CD 接入完成！

📄 生成的文件：
  - .drone.yml
  - scripts/deploy-remote.sh

🔧 Drone 面板配置（需手动）：
  - [x] 仓库已激活
  - [x] Trusted 已开启
  - [x] Secrets 已添加
  - [ ] Cron Job（可选）

🖥️ 生产服务器：
  - [ ] .env 已配置
  - [ ] deploy-remote.sh 已复制
  - [ ] 首次部署成功

📖 回滚方案：
  方式1: ssh 到生产服务器执行 bash scripts/deploy-remote.sh {旧版本tag}
  方式2: git tag {旧版本}-rollback {旧版本} && git push origin {旧版本}-rollback

主人，用不用我沉淀 or git 提交？
```

---

## 附录：基础设施搭建

当用户表示基础设施未就绪时，按需输出以下指引：

### A. Drone CI 部署

在 Drone CI 服务器创建 `~/drone/docker-compose.yml`：

```yaml
services:
  drone-server:
    image: drone/drone:2
    container_name: drone-server
    restart: always
    ports:
      - "3080:80"
    environment:
      - DRONE_GITEA_SERVER=https://<your-gitea-domain>
      - DRONE_GITEA_CLIENT_ID=<gitea-oauth-client-id>
      - DRONE_GITEA_CLIENT_SECRET=<gitea-oauth-client-secret>
      - DRONE_SERVER_HOST=<your-drone-domain>
      - DRONE_SERVER_PROTO=https
      - DRONE_RPC_SECRET=<openssl rand -hex 16 生成>
      - DRONE_USER_CREATE=username:<gitea用户名>,admin:true
    volumes:
      - ./data:/data

  drone-runner:
    image: drone/drone-runner-docker:1
    container_name: drone-runner
    restart: always
    depends_on:
      - drone-server
    environment:
      - DRONE_RPC_PROTO=http
      - DRONE_RPC_HOST=drone-server
      - DRONE_RPC_SECRET=<与 server 相同>
      - DRONE_RUNNER_CAPACITY=2
      - DRONE_RUNNER_NAME=drone-runner-1
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
```

关键注意：
- `DRONE_RPC_PROTO=http`：Runner 走 Docker 内网直连，不走 HTTPS
- `DRONE_USER_CREATE` 的 username 必须与 Gitea **登录用户名**完全一致（不是邮箱）

### B. 私有 Registry

```bash
docker run -d --name registry \
  -p 5000:5000 \
  -v /opt/registry-data:/var/lib/registry \
  --restart always \
  registry:2
```

### C. insecure-registries 配置

在 Drone CI 服务器和生产服务器的 `/etc/docker/daemon.json` 添加：

```json
{
  "insecure-registries": ["<registry-host>:5000"]
}
```

**不要带 `http://` 前缀**，直接写 `host:port`。修改后 `sudo systemctl restart docker`。

### D. SSH 免密

```bash
# Drone CI 服务器上生成密钥
ssh-keygen -t ed25519 -C "drone-ci-deploy" -f ~/.ssh/drone_deploy -N ""

# 将公钥添加到生产服务器
ssh-copy-id -i ~/.ssh/drone_deploy.pub -p <port> <user>@<production-ip>

# 验证
ssh -i ~/.ssh/drone_deploy -p <port> <user>@<production-ip> "echo ok"
```

---

## 踩坑清单（生成配置时必须规避）

| # | 坑 | 正确做法 |
|---|-----|---------|
| 1 | `insecure-registries` 带 `http://` 前缀 | 直接写 `host:port` |
| 2 | Drone `${VAR}` 与 shell 变量冲突 | 直接用 `${DRONE_TAG:-latest}`，不赋中间变量 |
| 3 | 用 `secrets:` 字段注入 secret | 用 `environment: { VAR: { from_secret: name } }` |
| 4 | `plugins/docker` DinD 启动失败 | 用 `docker:27-cli` + 挂载 Docker socket |
| 5 | `DRONE_USER_CREATE` 填邮箱 | 必须填 Gitea 登录用户名 |
| 6 | `event + cron` 触发条件互斥 | 只用 `event: [tag, cron]`，不加 `cron:` 过滤 |
| 7 | Registry 地址不一致（IP vs 域名） | Drone Secret、`.env`、compose 三处统一 |
| 8 | SSH 端口不对 | `appleboy/drone-ssh` 显式指定 `port` |
| 9 | Docker 权限不足 | `sudo usermod -aG docker <user>` 后重新登录 |
| 10 | `daemon.json` 被覆盖 | 修改前先 cat 查看，合并内容 |

---

## 故障排查速查表

| 现象 | 检查方向 |
|------|---------|
| Pipeline 不触发 | Gitea Webhook 是否勾选"创建"事件；`.drone.yml` trigger |
| Step 一直 pending | Runner 是否连通 Server；仓库是否 Trusted |
| 构建报 secret 为空 | `environment: from_secret` 而非 `secrets:` |
| Docker push 失败 (HTTPS) | 两台服务器 `insecure-registries` 配置 |
| SSH 部署超时 | 密钥是否正确；端口是否匹配；Docker 权限 |
| 镜像名 invalid reference | `.env` 的 `DOCKER_REGISTRY` 变量是否正确 |
| 数据库迁移失败 | `docker compose logs -f <service>` |
| 健康检查超时 | 增大 `MAX_ATTEMPTS`；检查服务启动日志 |