生产部署整改阶段检查点

This commit is contained in:
xuans committed 2026-08-31 23:33:56 +08:00
1 parent f3348cf95d
commit 92d4b3d398
56 files changed
+4178 -240

No files matched your search

+298
View File
@@ -0,0 +1,298 @@
# Scert 生产部署与运维说明
## 1. 文档范围
本文档用于 Scert `0.1.0` 的 Linux 生产部署、升级、备份、恢复、监控和故障处理。当前测试拓扑为:
| 主机 | 用途 | 允许部署内容 |
| --- | --- | --- |
| `192.168.2.3` | Scert 服务主机 | Scert、systemd unit、Nginx 反向代理 |
| `192.168.2.4` | SSH 和证书推送目标 | SSH、公钥、证书目标目录、Nginx;禁止部署 Scert |
开发验收端口:
- Scert:`127.0.0.1:9004`
- Nginx:`0.0.0.0:9003`
正式生产通常由 Nginx 监听 `443`。`9003` 只用于当前隔离网络开发测试,`9004` 必须保持回环监听,不得对公网开放。
## 2. 生产准入条件
部署前必须全部满足:
- [ ] 使用 Go `1.26.6` 或更高兼容安全版本完成发布构建。
- [ ] `go test -count=1 ./...`、`go test -race -count=1 ./...`、`go vet ./...`、`go mod verify` 和 `govulncheck ./...` 通过。
- [ ] Web 前端生产构建通过,生产依赖不存在高危或严重漏洞。
- [ ] Linux amd64 发布包中的 `scert`、`scert-admin`、`web/`、systemd unit 和安装器来自同一提交。
- [ ] 目标主机时间同步正常,系统 CA、OpenSSH、Nginx 和安全更新处于受支持状态。
- [ ] Scert 仅绑定 `127.0.0.1`,Nginx 到 Scert 的 HTTPS 上游证书校验已开启。
- [ ] 已完成一次停服完整备份、篡改拒绝、恢复和失败回滚演练。
- [ ] 已确认 SSH 主机指纹并验证证书推送、私钥权限、Nginx 重载和失败回滚。
- [ ] 管理员账号使用独立强密码,DNS、SMTP、HTTP 通知和 SSH 私钥没有写入代码、日志、文档或 Git。
任何一项未满足时,只能作为开发或受控试运行环境,不能宣称正式生产准入。
## 3. 发布构建
### 3.1 后端验证
```bash
cd backend
go test -count=1 ./...
go test -race -count=1 ./...
go vet ./...
go mod verify
govulncheck ./...
```
### 3.2 Web 构建
```bash
cd frontend
npm ci
npm run build
npm audit --omit=dev --audit-level=high
```
### 3.3 Linux amd64 二进制
```bash
cd backend
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
go build -trimpath -ldflags "-s -w" -o ../release/linux-amd64/scert ./cmd/scert
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
go build -trimpath -ldflags "-s -w" -o ../release/linux-amd64/scert-admin ./cmd/scert-admin
```
发布目录必须包含:
```text
linux-amd64/
├── install-linux.sh
├── scert
├── scert-admin
├── web/
└── systemd/
```
发布包应额外生成 SHA-256 清单并通过可信通道核对。安装器会再次验证二进制是 Linux amd64 ELF,并拒绝符号链接或特殊 Web 文件。
## 4. Linux 安装与升级
### 4.1 首次安装
```bash
chmod +x install-linux.sh scert scert-admin
sudo ./install-linux.sh --source-dir . --certificate-dir /ssl
```
安装器不会自动启动服务,也不会创建公网防火墙规则。完成初始化并核对配置后执行:
```bash
sudo systemctl daemon-reload
sudo systemctl enable Scert
sudo systemctl start Scert
sudo systemctl status Scert --no-pager -l
```
### 4.2 升级
安装器禁止在 `Scert.service` 或 `Scert-admin.service` 运行时覆盖程序。升级顺序:
```bash
sudo systemctl stop Scert-admin
sudo systemctl stop Scert
sudo -u Scert /scert/scert --config /scert/conf/scert.json backup
sudo ./install-linux.sh --source-dir /tmp/scert-linux-amd64
sudo systemctl start Scert
sudo systemctl status Scert --no-pager -l
```
没有显式传入 `--certificate-dir` 时,升级会读取 `/scert/conf/installation.json` 并保留既有证书根目录。升级不得覆盖 `/scert/conf/scert.json`、数据库、主密钥、敏感配置、证书和备份。
### 4.3 systemd 安全边界
主服务使用独立 `Scert` 用户、`UMask=0077`、`NoNewPrivileges`、私有设备和临时目录、内核与控制组保护、只读系统目录和受限地址族。安装后必须验证:
```bash
sudo systemd-analyze verify /etc/systemd/system/Scert.service
sudo systemd-analyze security Scert.service
sudo systemctl show Scert -p User -p Group -p NoNewPrivileges -p ProtectSystem
```
不得为方便调试改成 `root` 运行,也不得扩大 `ReadWritePaths` 到整个文件系统。
## 5. 网络与反向代理
### 5.1 Scert 监听
生产配置或 systemd 环境覆盖:
```text
SCERT_SERVER_HOST=127.0.0.1
SCERT_SERVER_PORT=9004
SCERT_SERVER_HTTPS_MODE=proxy
SCERT_WEB_ENABLED=true
```
验证:
```bash
sudo ss -lntp | grep 9004
curl -k --fail --silent --show-error https://127.0.0.1:9004/healthz
curl -k --fail --silent --show-error https://127.0.0.1:9004/readyz
```
`ss` 结果必须是 `127.0.0.1:9004` 或 `[::1]:9004`,不能是 `0.0.0.0:9004`。
`/healthz` 只用于存活检查;返回 HTTP `200` 仅表示 Scert 进程和 HTTP 服务可响应。`/readyz` 才是生产就绪检查,安装、升级、恢复、配置变更、Nginx 切流和监控告警均必须以它为准。
`/readyz` 只有在以下条件全部满足时返回 HTTP `200`:
- 初始化已完成。
- DNS 凭据引用存在并且可解密。
- 已配置的 HTTP 通知和 SMTP 通知凭据可解密。
- 内部 TLS 证书和私钥存在、是普通文件且不是符号链接。
- 数据库连接检查成功。
失败时返回 HTTP `503`,原因码不包含完整敏感信息引用:
| 原因码 | 处理要求 |
| --- | --- |
| `setup_incomplete` | 完成初始化流程。 |
| `dns_credential_missing` | 通过管理页面配置 DNS Provider 并完成在线 API 测试。 |
| `secret_store_unavailable` | 检查 `master.key`、`secrets.json` 和配置目录权限。 |
| `credential_unavailable` | 重新录入真实 DNS、HTTP 通知或 SMTP 通知凭据;禁止写入假 Token 绕过。 |
| `tls_material_unavailable` | 检查内部 TLS 证书和私钥路径、文件类型与权限。 |
| `database_unavailable` | 检查 SQLite 文件、MySQL 连通性、账户权限和连接限制。 |
`/healthz` 返回正常而 `/readyz` 返回 `503` 时,服务只能用于故障排查,不能接收生产流量。
### 5.2 Nginx
生产 Nginx 对外通常只开放 `443/tcp`;如需 HTTP 跳转,再开放 `80/tcp`。Nginx 到 Scert 必须配置:
```nginx
proxy_ssl_server_name on;
proxy_ssl_name scert.example.com;
proxy_ssl_verify on;
proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;
proxy_ssl_verify_depth 3;
```
生产配置禁止 `proxy_ssl_verify off`。私有 CA 应使用 root 管理的独立 CA 文件。当前 `9003` 测试入口不得开放到公网。
## 6. 防火墙
生产建议:
| 端口 | 来源 | 用途 | 要求 |
| --- | --- | --- | --- |
| `22/tcp` | 管理网段 | SSH 运维和证书推送 | 限制来源地址,优先仅允许密钥认证 |
| `443/tcp` | 业务访问网段 | Nginx HTTPS | 正式生产入口 |
| `80/tcp` | 可选 | HTTP 到 HTTPS 跳转 | 不使用跳转时关闭 |
| `9004/tcp` | 无外部来源 | Scert 内部端口 | 只绑定回环,不创建放行规则 |
| `9003/tcp` | 仅开发测试网段 | 当前 Nginx 测试入口 | 禁止公网开放 |
云安全组和主机防火墙必须同时核对,不能只配置其中一层。
## 7. 备份
### 7.1 备份内容
完整备份包含:
- `scert.json`
- `master.key`
- `secrets.json`
- `scert.db` 或 `scert.sql`
- `certificates/`
- `manifest.json`
SQLite 使用 `VACUUM INTO` 创建一致性快照并执行 `PRAGMA quick_check`。清单记录相对路径、权限、大小和 SHA-256。日志和数据库审计记录默认保留 30 天;文件日志每天最多写入 5 MiB,超过后停止文件写入但保留标准输出日志。
### 7.2 停服备份
```bash
sudo systemctl stop Scert
sudo -u Scert /scert/scert --config /scert/conf/scert.json backup
sudo systemctl start Scert
```
程序会获取 `/scert/data/scert.lock` 跨进程维护锁。即使存在维护锁,生产流程仍必须停服,因为证书目录还可能被外部部署工具修改。
备份目录必须保持 `0700`,并复制到加密、离线或不可变存储。`manifest.json` 不是数字签名,不能替代备份介质权限、异地副本和访问审计。
## 8. 恢复
恢复前先复制当前完整数据目录和证书目录到受保护位置,然后执行:
```bash
sudo systemctl stop Scert
sudo -u Scert /scert/scert --config /scert/conf/scert.json \
restore --input /scert/backups/scert-YYYYMMDD-HHMMSS
sudo systemctl start Scert
```
恢复会拒绝:
- 缺少或被篡改的清单。
- 符号链接、特殊文件、异常权限、大小或 SHA-256。
- 跨配置目录、数据目录、证书目录、备份目录或数据库目标恢复。
- 无法解密的敏感配置引用。
- 主服务或另一个维护任务持有进程锁。
恢复前副本使用 `*.before-restore-YYYYMMDD-HHMMSS` 命名。失败时程序会尝试整体回滚;完成后必须验证健康接口、登录、域名列表、证书读取、SSH 推送和 Nginx HTTPS。
## 9. SSH 与证书推送
`192.168.2.4` 仅作为推送目标,不安装 Scert。每台主机、每次配置都必须生成随机公钥名称:
```text
/ssl/ssh/用户名+scert-随机值
```
验收要求:
- 首次连接人工核对 SSH 主机指纹。
- 主机指纹变化时拒绝连接,禁止自动接受新指纹。
- `cert.pem`、`fullchain.pem` 权限为 `0644`,`privkey.pem` 为 `0600`。
- 使用临时文件和原子重命名替换证书。
- Nginx 配置测试成功后才执行 reload。
- 推送、校验或 reload 失败时恢复旧证书。
- 临时私钥、密码、Token 和完整连接串不得写入日志。
## 10. 监控与日常检查
建议至少监控:
- `/healthz` 状态和响应时间。
- `/readyz` 生产就绪状态;连续返回 `503` 时停止切流并立即告警。
- systemd 服务状态、重启次数和退出码。
- 证书剩余有效期;默认续期阈值为 6 天,3 天进入紧急状态。
- 证书申请、部署、校验和通知任务失败数量。
- 文件系统剩余空间、SQLite/MySQL 可用性和备份最后成功时间。
- Nginx 5xx、上游 TLS 校验失败和 SSH 主机指纹变化。
常用命令:
```bash
sudo systemctl status Scert --no-pager -l
sudo journalctl -u Scert --since "1 hour ago" --no-pager
sudo ss -lntp | grep -E ':(443|9003|9004)\b'
sudo -u Scert /scert/scert --config /scert/conf/scert.json status
```
日志输出不得包含 DNS Token、SMTP 密码、HTTP 通知密钥、SSH 私钥、超级管理员密码或会话 Cookie。
## 11. 当前外部验收边界
以下项目必须有真实外部环境和合法凭据才能完成,不能由本地自动化测试替代:
- 真实 DNS Provider API 的最小权限凭据与在线写入/清理验证。
- 合法域名的 Let’s Encrypt Production 申请、续期和速率限制处理。
- MySQL 5.7 与 8.0 的真实备份、恢复和失败回滚。
- Windows Service 安装、升级、开机启动、停止和 ACL。
- 公网生产 Nginx、真实证书链和最终业务访问。
这些外部项未完成时,可以批准 Linux + SQLite 的受控试运行,但不得把未验证能力写成已通过。