Files
novalon-website/docs/deployment/cicd/README.md
T
zhangxiang becb9407bd feat(gitea): 升 28.2.0 并把品牌装饰层纳管为可重跑的仓库真源
自建 Gitea 此前是出厂外观(茶杯标 + 「Gitea: Git with a cup of tea」标题),而品牌「纯字标 + 朱砂条」已在官网落地;同时现网 1.27.2
  落后两个安全版本 —— 1.27.3 的 fix(git): restrict hook permissions 打的正是本实例 8 月被入侵所用的 packObjectsHook
  向量。装饰基准取自升级后从容器抽出的真实模板,不凭记忆手写。

- 升级 28.2.0:pg_dump 后还原到一次性探针库对账(116 表 / 20 仓库 / 8 用户全等),停服 8s;28.0.0 的 git egress BREAKING
  按裁定收为 EGRESS_MODE=strict(实测 app.ini 无旧 ALLOWED_* 键、mirror 仓库 0 个 ⇒ 空白名单不伤业务)。

- 装饰层真源入库 infra/cicd/gitea-custom/(结构即实测 CustomPath=/data/gitea):页头/OG/默认头像换简标与刻版、novalon-
  brand.css 覆盖 --color-primary 全色阶、custom/header.tmpl 外链注入、signin_inner.tmpl
  登录页加字标锁定(220×103)。

- 色阶由脚本生成并自带夹具:先对上游 14 档对账(light/dark 两档 ramp 命名互为反向,手敲必错),再喂上游蓝做反向自证,双双通过才写盘。

- 深档按钮改「黑字朱底」:Gitea 用同一令牌既当按钮底色又当链接文字色,AA 区间为空(按钮白字 L≤0.1833 vs 链接 on #1e1f20 L≥0.2362)⇒ #E13C58
  × #0D0D0D 实测 4.62:1;深档链接 3.92:1 作为已登记让步保留(上游蓝同位 4.14,本就不达标)。

- deploy/verify 带预检、备份、内容 sha256 比对、负对照与 0/1/2/3 退出码分档,核心判红自动回滚(首轮就靠它把「标题未生效」与「装饰未生效」区分开)。

- 纠正两处生产口径失真:仓库那份「加固版」compose 从未上线(真实文件纳管为 infra/cicd/gitea/docker-compose.live.yml);生产
  REQUIRE_SIGNIN_VIEW 实为 false,且 compose 的 DISABLE_REGISTRATION=false 会经 environment-to-ini
  在重建时静默打开注册 —— 已对齐为 true。遗留的匿名浏览面与 SSH_PORT 错配只登记不擅动。
2026-10-22 18:55:55 +08:00

97 lines
7.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# CI/CD 生产环境:Gitea + Jenkins 运维文档
> 基准日期:2026-09-14。本文所有数据来自对生产服务器 `139.155.109.62` 的实测(SSH 探测 + HTTP 探测),
> 非泛泛的最佳实践摘抄。配置源码在 [`infra/cicd/`](../../../infra/cicd/)。
## 文档索引
| 文档 | 内容 |
|------|------|
| [01-installation.md](01-installation.md) | 安装部署、安全加固、Gitea↔Jenkins 集成、webhook 排障 |
| [02-ha-backup-monitoring.md](02-ha-backup-monitoring.md) | 高可用、备份与恢复、日志与监控 |
| [03-credential-incident.md](03-credential-incident.md) | **P0**:凭据入库事故与处置清单(待执行) |
## 当前架构(实测)
```
┌────────────────────────────────────┐
│ 139.155.109.62 (VM-0-15-debian) │
│ Debian · Docker 20.10.24 │
│ │
推送 git push ────────┐│ novalon-nginx-secure (nginx:alpine)│
│ :80/:443 终止 TLS + HSTS │
│ └──────┬──────────────┬──────────────┘
│ │ │
│ git.f.novalon.cn ci.f.novalon.cn
│ │ │
│ upstream gitea_app upstream jenkins_app
│ │ │
│ ┌───────▼─────┐ ┌─────▼──────┐
│ │ gitea │ │ jenkins │
└─────────►│ 28.2.0 │ │ 2.568.1 │
│ :3001(本机) │ │ :8080(本机) │
│ :2222 SSH │ └─────┬──────┘
└───────┬─────┘ │
│ │ rsync+ssh
┌───────▼─────┐ │
│ postgresql │ ▼
│ 17-alpine │ /home/novalon/docker-app/
└─────────────┘ novalon-website(Next.js)
```
- 代码仓库:`git.f.novalon.cn/novalon/novalon-website`(本仓库 `origin` 即指向此处)
- 流水线:`Jenkinsfile`(仓库根目录),作业名 `novalon-website-ci-cd`
- 触发:Gitea push → webhook → Jenkins `GenericTrigger` → 构建/测试 → `scripts/deploy.sh` rsync 发布
- 反代与 TLS:`nginx-static-production.conf` 定义 upstream,`conf.d/*.conf` 定义 server 块
## 2026-10-22 升级与品牌化(实测回填)
- **版本**:`gitea/gitea:1.27.2` → **`28.2.0`**(上游已改版本号:`1.27.x → 28.x`)。1.27.3 含 16 条 SECURITY 修复,其中 `fix(git): restrict hook permissions`(#39008)打的正是本实例 8 月被入侵所用的 `packObjectsHook` 向量,28.x 一并收进来;另新增**审计日志**(#38189)与 WebSocket 通知(#36965,`conf.d/git.f.novalon.cn.conf:36-38` 已有 `Upgrade` 头,无需改 nginx)。
- **BREAKING 已处理**:28.0.0 把所有 git 出站操作改走内部 forward proxy,旧 `ALLOWED_DOMAINS/BLOCKED_DOMAINS/ALLOW_LOCALNETWORKS` 作废,改 `[security] EGRESS_MODE = lax|strict` + `ALLOWED_HOST_LIST`(新语法:`*.example.com` 只匹配子域、IP 不支持通配符、`*` 不再是合法条目、非标准端口须显式列出)。实测 app.ini 里**没有任何旧键**、DB 里 **mirror 仓库 = 0** ⇒ 已按裁定设 `EGRESS_MODE=strict` + 空白名单(未来用「从 URL 迁移」需先加白名单)。
- **升级过程**:现场 `pg_dump`(61MB,**不是**文档旧记录的 1.7MB)→ 还原到一次性探针库对账(116 表 / 20 仓库 / 8 用户全对上)→ 改 compose image tag → `docker-compose up -d` → 停服 **8s** 后 healthz 200。回滚锚点:旧镜像 `e8be8e1f776f`(daocloud 镜像站)、`/root/gitea-pre28-*.sql`、`docker-compose.yml.bak-*`。
- **⚠ 两处文档失真已纠正**(详见 `CONTEXT.md` 「CI 生产口径的两处失真」行):
1. 本文件与 `infra/cicd/docker-compose.gitea.yml` 描述的「加固版」**从未上线**;生产实跑 `/home/novalon/docker-app/novalon-cicd/gitea/docker-compose.yml`,现已纳管为 `infra/cicd/gitea/docker-compose.live.yml`。
2. `REQUIRE_SIGNIN_VIEW` 生产是 **false**(`/` 303 → `/explore`,匿名可浏览仓库列表),不是文档写的 true。另:`/etc/s6/gitea/setup:60` 每次启动都跑 `environment-to-ini`,compose 里 `DISABLE_REGISTRATION=false` 会在重建容器时**静默打开注册**——本轮已把它对齐成与 app.ini 一致的 true。
- **品牌装饰层**:图标/主色/登录页换成「睿新致遠 / NOVALON」,真源是仓库里的 `infra/cicd/gitea-custom/`(结构即 `$GITEA_CUSTOM`,实测 `CustomPath=/data/gitea`),部署与回滚见其 README。**未做**:匿名浏览面收口、`SSH_PORT=22` 与宿主 `2222:22` 的克隆地址错配。
## 2026-09-14 审计结论
### 已就绪(无需改动)
| 项 | 实测证据 |
|----|----------|
| HTTPS + HSTS | 两域名均 `strict-transport-security: max-age=63072000` |
| Gitea Cookie 安全 | `i_like_gitea` 带 `HttpOnly; Secure; SameSite=Lax` |
| 作业与插件齐备 | `gitea`、`generic-webhook-trigger`、`credentials-binding` 已装 |
| 反向代理信任链 | `REVERSE_PROXY_TRUSTED_PROXIES=172.20.0.0/16,127.0.0.1` |
| 服务端口不外暴 | Gitea/Jenkins HTTP 均仅 `127.0.0.1`,只有 nginx 占 80/443 |
### 发现的问题(按严重度)
| 级别 | 问题 | 证据 | 状态 |
|------|------|------|------|
| **P0** | 真实凭据已提交 git 并推送公网 | `cicd.config` Gitea/Jenkins 密码、OAuth2 secret | 待处置([03](03-credential-incident.md)) |
| **P0** | Jenkins 从未备份 | `backup.sh` 存在但 crontab 无此项,`/home/novalon/backups/` 不存在 | ✅ 已修复 |
| **P1** | 磁盘 20G 用 85–90% | `df -h /` → 88% used, 2.4G avail | ⚠️ 需扩容/异地 |
| **P1** | Jenkins 以 root 运行 + 挂 docker.sock + /root/.ssh | compose `user: root`;作业实测 0 处 docker 调用 | 配置已备好,待维护窗口 |
| **P1** | Gitea SSH 克隆地址不可用 | `app.ini SSH_PORT=22`,实际暴露 `0.0.0.0:2222` | 配置已备好 |
| **P2** | 容器日志轮转未生效 | Gitea 单份日志 849MB(compose 配置在,运行容器 `LogConfig={}`) | ✅ 已截断+兜底 cron |
| **P2** | Gitea 数据库零备份 | `postgresql_backup/` 为空 | ✅ 已修复 |
| **P3** | 安全头重复注入 | Gitea 响应 `x-frame-options` 出现两次(nginx + 应用) | 低优先 |
## 快速操作
```bash
# 备份(薄:仅 DB + Jenkins 配置,约 2MB)
ssh root@139.155.109.62 '/home/novalon/docker-app/infra/cicd/backup/backup-cicd.sh --skip-repos'
# 备份(全量:含 Gitea 裸库,约 940MB)
ssh root@139.155.109.62 '/home/novalon/docker-app/infra/cicd/backup/backup-cicd.sh'
# 健康检查(6 维度,FAIL 时 exit 1)
ssh root@139.155.109.62 '/home/novalon/docker-app/infra/cicd/monitoring/healthcheck-cicd.sh'
# 已装的定时任务
ssh root@139.155.109.62 'crontab -l | grep infra/cicd'
```