DevOps 系统指南

这套系统解决什么问题

这一章回答第一个疑问：我们到底在解决什么麻烦？为什么小团队也需要一套「系统」？

想象一下没有这套系统时的日常：需求记在聊天软件里，聊着聊着就沉底了；代码在各自电脑上，靠 U 盘和口头同步；测试靠人肉点一遍，点漏了就上线即事故；部署靠「我记得那台服务器上好像是这么改的」；crontab（定时任务）改完就忘，三个月没人知道某台机器凌晨 3 点在跑什么。

这套系统要解决的，就是把这一切从人脑记忆里搬出来，变成代码和自动化。源文档把需求拆成了 7 块，外加 1 条贯穿性需求，用大白话说就是：

注意第 8 条：这个团队里有一位特殊成员——运行在你个人工作电脑上的 AI coding agent（可以理解为一位会读写代码、会执行命令的 AI 同事）。整套系统的每一个设计决策，都会考虑到「人和 AI 都能用」：一切配置都是文本文件、一切操作都有固定流程，因为 AI 擅长读写文本、按手册执行，不擅长点网页、靠感觉办事。

30 秒看懂全貌

这一章解决「东西太多记不住」的问题：先用六句话记住骨架，再学会认颜色——后文所有图和标记都用同一套颜色。

源文档的最后一页有个「一页纸总结」，它就是整套系统的骨架：

• 一个中心：GitLab CE（放在办公网），承载 Issue、代码、CI/CD 调度、容器镜像仓库；
• 一个执行者：GitLab Runner（和 GitLab 同一台机器），实际跑一切自动化任务；
• 一种模型：全部走 SSH 推送——Ansible 管服务/定时任务/脚本，部署走同一套 playbook；纯内网机器经文件服务器跳板到达，内网机器零 agent、零出网需求；
• 一个事实来源：ops 仓库（服务器的一切）+ 各项目仓库（代码的一切），一切改动走合并请求（MR）；
• 一把钥匙：SOPS + age，密钥加密后存 Git，明文永不进仓库；
• 一套手册：skill 库让 AI agent 按固定流程做开发、部署、运维，模板内嵌、红线明确、全程留痕。

学会读颜色

本文给系统里的每类「角色」分配了一个固定颜色，架构图、数据流图、正文标记全部通用。读完你会自然形成条件反射：

一句话概括这套系统的工作方式：所有事情从办公网一侧发起，经 SSH 推到目标机器；所有事实写在 Git 仓库里；所有重复劳动交给流水线和 AI agent。后面的每一章，都是对这句话某一个部分的展开。

需要几台什么样的机器

这一章回答「我要准备什么硬件」：先给一张采购/盘点清单，再用一张可点击的拓扑图看懂它们怎么连。

机器清单（照单盘点即可）

一句话：新增的只有一台 4C8G 的办公网机器，其余全是现有机器的角色明确化。

GitLab 为什么放办公网？

候选位置有三个，源文档逐一分析过：

为什么不能放纯内网？因为纯内网里的 GitLab 无法访问公网，装依赖、拉基础镜像、更新系统都极痛苦；而且你在办公网访问它还要绕跳板，日常体验差。

这里藏着全篇最重要的一个洞察：内网机器从头到尾都不需要主动访问 GitLab。想通这一点，就引出了下一章的核心决策。

最重要的一个决策：推送而不是拉取

这一章讲透整套系统最有价值的设计选择——为什么内网机器上可以什么都不装。理解了它，后面所有工具的选择都顺理成章。

两种部署模型

「把代码部署到服务器」这件事，业界有两种经典做法：

你们的网络里恰好存在这样一条链路：

办公网（GitLab Runner / 你的电脑）──SSH──► 文件服务器 ──SSH──► 纯内网机器

SSH 原生支持多级跳板（ProxyJump，下面详解），Ansible 也是纯 SSH 推送。所以整套系统的控制流和数据流统一为：

从办公网一侧发起，经 SSH 推送。纯内网机器上不需要安装任何常驻 agent，不需要任何特殊网络配置，只要能被文件服务器 SSH 到即可。

这就是「内网机器零 agent」的全部秘密——不是用了什么黑科技，而是选了一个贴合你们网络条件的模型。

ProxyJump：一次 SSH 穿越跳板的三步原理

从 Runner（或你的电脑）到纯内网机器，中间隔着文件服务器。SSH 的 -J / ProxyJump 选项能把多级跳转压缩成一条命令：

ssh -J ops@<文件服务器IP> deploy@<内网机器IP>

很多人在这里有误解，以为「跳板机替我登录了内网机器」。实际上它的工作原理分三步，务必看清：

1. 你的 SSH 客户端先和文件服务器建立连接，用你的私钥认证（文件服务器上存你的公钥）；
2. 文件服务器只做一件事：在它和内网机器之间转发 TCP 流量——相当于一根网线；
3. 你的客户端再通过这根「网线」和内网机器做认证——还是你的私钥对内网机器上你的公钥。认证是端到端加密的，文件服务器看不到也解不开内容。

结论非常关键：文件服务器上不需要存任何到内网机器的私钥，它只要网络可达内网机器即可。即使文件服务器被入侵，攻击者拿到的也只是「能向内网机器发起 TCP 连接」的能力，没有钥匙。这比「先 ssh 到文件服务器、再在文件服务器上存一把私钥 ssh 到内网」安全得多。

把跳转关系写进配置，以后无感

# 跳板：文件服务器
Host fileserver
  HostName <文件服务器IP>
  User ops                      # 文件服务器上专门开的跳板账号，权限最小化
  IdentityFile ~/.ssh/id_ed25519

# 办公网生产机（直连）
Host office-*
  User deploy
  IdentityFile ~/.ssh/id_ed25519

# 纯内网生产机（自动走跳板）
Host intranet-*
  User deploy
  ProxyJump fileserver
  IdentityFile ~/.ssh/id_ed25519

技术栈逐个讲

这一章把每个工具单独讲透：它是什么、本身能做什么、在这套系统里承担哪几项功能、为什么选它。顺序按「从代码到服务器」的链路排列。

services:
  gitlab:
    image: gitlab/gitlab-ce:latest
    container_name: gitlab
    hostname: gitlab.<公司内网域名或直接用IP>
    restart: always
    ports:
      - "8080:80"      # Web 界面：浏览器访问 http://<服务器IP>:8080
      - "8929:22"      # Git over SSH：clone 地址里会带这个端口
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'http://<服务器IP>:8080'
        gitlab_rails['gitlab_shell_ssh_port'] = 8929
    volumes:
      - /opt/gitlab/config:/etc/gitlab
      - /opt/gitlab/logs:/var/log/gitlab
      - /opt/gitlab/data:/var/opt/gitlab
    shm_size: '256m'

sudo gitlab-runner register \
  --url "http://<服务器IP>:8080" \
  --token "<注册token>" \
  --executor "docker" \
  --docker-image "docker:26" \
  --description "office-runner" \
  --tag-list "office,deploy" \
  --docker-volumes "/var/run/docker.sock:/var/run/docker.sock"

[[runners]]
  [runners.docker]
    volumes = ["/var/run/docker.sock:/var/run/docker.sock",
               "/opt/runner-ssh:/home/gitlab-runner/.ssh:ro"]

stages:
  - test        # 自动化测试：代码质量的自动闸门
  - build       # 构建：产出可部署的制品
  - deploy      # 部署：推到服务器（默认手动触发）

lint:
  stage: test
  script:
    - <你的lint命令>     # 例如 ruff check . / npm run lint
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"   # 开 MR 时跑
    - if: $CI_COMMIT_BRANCH == "main"

unit-test:
  stage: test
  script:
    - <你的单测命令>     # 例如 pytest / npm test / go test ./...
  artifacts:
    reports:
      junit: report.xml   # 测试报告直接显示在 MR 页面
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == "main"

build:
  stage: build
  script:
    - <你的构建命令>
    - tar czf app-$CI_COMMIT_SHORT_SHA.tar.gz <产物路径>
  artifacts:
    paths:
      - app-*.tar.gz      # 制品存到 GitLab，回滚也能取到
    expire_in: 30 days
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
    - if: $CI_COMMIT_TAG  # 打 tag 时构建正式发布版

ansible office-web1 -m systemd -a "name=app state=restarted"   # 重启某服务
ansible prod -m shell -a "systemctl status app --no-pager"     # 看所有生产机服务状态
ansible intranet-app1 -m command -a "/opt/ops-scripts/cleanup-logs.sh --days 30"

cron_jobs:
  - name: 清理30天前的日志
    hosts: prod
    user: deploy
    minute: "30"
    hour: "3"
    job: /opt/ops-scripts/cleanup-logs.sh --days 30
  - name: 每日对账
    hosts: intranet-app1          # 只在指定机器跑
    user: deploy
    minute: "0"
    hour: "6"
    job: /opt/ops-scripts/daily-reconcile.sh

[Unit]
Description={{ app_name }}
After=network.target

[Service]
Type=simple
User={{ app_user }}
WorkingDirectory=/opt/{{ app_name }}
ExecStart=/opt/{{ app_name }}/current/<启动命令>
Restart=always
RestartSec=5
EnvironmentFile=/opt/{{ app_name }}/.env    # 密钥从这里注入

[Install]
WantedBy=multi-user.target

db_password: ENC[AES256_GCM,data:K8s3j...,type:str]
api_key: ENC[AES256_GCM,data:mV92k...,type:str]
sops:
  age:
    - recipient: age1ql3z7hjy54pw3hyww5sny43kmt9acvz...   # 谁能解密，写在文件里

---
name: deploy-service
description: 将指定服务部署到指定环境。当用户要求部署、发版、上线、回滚时使用。
---

## 执行步骤
1. 运行 scripts/precheck.sh：确认目标机可达（内网自动走 ProxyJump）、
   磁盘 >20%、负载正常。任一失败则停止并报告。
2. Dry-run：ansible-playbook ... --check --diff，将 diff 摘要汇报给用户。
3. 等待用户明确确认。未确认前禁止进入下一步。
4. 正式执行同一命令（去掉 --check --diff）。
5. 运行 scripts/healthcheck.sh：检查 systemd 状态 + 应用健康接口。
6. 汇报结果。失败时先运行 scripts/rollback.sh 再汇报。

## 红线
- 禁止跳过 dry-run 直接部署生产环境
- 禁止用 shell 模块临时拼凑部署命令，一切走 deploy-app.yml
- 部署涉及密钥时只通过 sops 解密注入，禁止把明文写入任何日志或回复

串起来：一个 bug 的一生

这一章把前面所有零件串成一条完整流水线：从有人提 bug，到修复上线，每一步谁在干活、经过哪些颜色。点击步骤条逐步看。

AI agent 协作闭环长这样

上面 7 步里，人的动作只有三个：提需求、评审点合并、确认部署。其余的重复劳动，你电脑上的 AI agent 都能按 skill 手册干完。源文档给的典型闭环对话是这样的：

注意两个设计细节：一是 推送模型的附带好处——CI 能做的事，agent 在你电脑上全能做，反之亦然，因为用的是同一套 playbook，不会出现「CI 里一套、本地一套」；二是 agent 的全部操作都落在 git 提交和 MR 上，天然可审计。

密钥怎么管

这一章回答「密码、私钥放哪才安全」：先把密钥分三类（不同类型的管理方式完全不同），再看私钥这把「钥匙的钥匙」怎么分布。

密钥三类分治

age 私钥的分布（整个密钥体系最要紧的一件事）

• 你本人：放在你电脑的 ~/.config/sops/age/keys.txt（AI agent 与你同机同权限，自然也能用）；
• 队友：各自电脑存一份（或通过你加密分发）；
• CI Runner：私钥内容存成 GitLab CI 变量 SOPS_AGE_KEY，勾选 Masked（日志自动打码）和 Protected（只有保护分支的流水线能读到——防止有人开个分支改 .gitlab-ci.yml 把密钥 echo 出来）；
• 离线备份：打印纸质或存加密 U 盘锁起来，与电脑分开放。私钥丢了 = 所有加密文件永久打不开。

密钥「落盘即结束」：部署时 sops -d --extract 只解密需要的字段，渲染进目标机的 /opt/app/.env（权限 600，属主 deploy），服务通过 systemd 的 EnvironmentFile= 读取。明文只存在于目标机的 600 权限文件和内存里——不进 Git、不进日志（Ansible 任务记得设 no_log: true）。

轮换也很简单：改密钥 = sops 编辑 → MR（diff 显示的是密文变化，安全）→ 合并 → 重跑部署 playbook → 重启服务，全程可审计。人员变动、怀疑泄露时轮换，每半年例行一次。

一切皆有出处：两个仓库的目录结构

这一章回答「东西都放在哪」：代码在项目仓库，服务器的一切在 ops 仓库，agent 的手册在 skills 目录。看完你就拿到了整套系统的「地图」。

ops 仓库：运维的唯一事实来源

从此以后，任何对服务器的改动 = 改这个仓库 + 跑 Ansible，禁止登服务器手工改。

ops/
├── ansible.cfg                  # Ansible 全局配置
├── inventories/
│   └── prod/
│       ├── hosts.ini            # 所有服务器的清单（含网络分组）
│       └── group_vars/          # 按组的变量（如内网组统一配 ProxyJump）
│           ├── office_prod.yml
│           └── intranet_prod.yml
├── playbooks/
│   ├── deploy-app.yml           # 部署应用
│   ├── services.yml             # 管理常驻服务（systemd）
│   ├── cron.yml                 # 管理定时任务
│   ├── scripts.yml              # 下发/更新运维脚本
│   └── bootstrap.yml            # 新服务器初始化
├── templates/
│   └── systemd/                 # systemd 服务文件模板
│       └── app.service.j2
├── files/
│   └── scripts/                 # 要下发到服务器的脚本的"母本"
│       ├── cleanup-logs.sh
│       └── sync-data.sh
└── secrets/                     # SOPS 加密的密钥文件
    └── prod.sops.yaml

# 办公网生产机
[office_prod]
office-web1
office-web2

# 纯内网生产机
[intranet_prod]
intranet-app1
intranet-db1

# 所有生产机
[prod:children]
office_prod
intranet_prod

ansible.cfg 里有两条值得知道的配置：host_key_checking = True（生产环境不要关主机指纹校验）和 pipelining = True（减少 SSH 往返，跑得快）。

skills 目录：agent 的手册架

skills/
└── deploy-service/                # skill 名 = 目录名
    ├── SKILL.md                   # 说明书：何时用、输入什么、一步步怎么做、红线是什么
    ├── templates/                 # 该操作需要的模板（systemd unit、MR 描述等）
    └── scripts/                   # 封装好的可执行脚本（precheck.sh、rollback.sh）

12 个 skill 的规划

落地时不必一次写全，第 5 周先写最高频的 5 个（work-on-issue、deploy-service、service-ops、cron-ops、secret-ops），其余随用随补：

为什么不选那些「明星工具」

这一章回答「别人都用的 X，我们为什么不用」：每个被劝退的工具都很有名，但对 小团队来说，不选它们的理由都很具体。

共同的原则只有一条：每多一个系统，就多一份要维护的东西、多一个「事实可能不一致」的地方。这套设计宁愿用朴素的工具把流程打通，也不用强大的工具把复杂度搬回家。

五周落地路线图

这一章回答「从哪开始动手」：不必一次到位，按依赖关系分五周走，每周结束都有可用的成果。

之后的迭代方向（用到再加，不提前建设）：监控告警（Uptime Kuma，一个容器就够）、预发（staging）环境、更多测试分层、更多 skill。

术语速查

看到黑话回来查这张表。每条都用人话解释。