生产部署整改阶段检查点

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

+87 -3
View File
@@ -38,12 +38,14 @@ sudo ./install-linux.sh --source-dir /tmp/scert-linux-amd64
安装器会:
1. 检查 Linux、root 权限、`systemctl` 和安装产物。
1. 检查 Linux、root 权限、`systemctl`、Linux amd64 ELF 安装产物、Web 特殊文件和符号链接。
2. 创建 `Scert` 系统用户和同名系统用户组,禁止交互式登录。
3. 创建 `/scert`、`/scert/conf`、`/scert/data`、`/scert/log`、`/scert/backups`、`/scert/docs`、`/scert/web` 和证书目录。
4. 安装 `scert`、`scert-admin`、Web 静态资源以及两个 systemd unit。
5. 设置安装目录、服务目录和配置目录权限,防止 `Scert` 运行用户替换 root 所有的程序文件。
6. 为证书根目录生成 systemd drop-in,并执行一次 `systemctl daemon-reload`。
7. 升级时读取并保留既有 `installation.json` 中的证书根目录;只有显式传入 `--certificate-dir` 才会变更。
8. 在复制程序前确认 `Scert.service` 和 `Scert-admin.service` 都已停止,并通过同文件系统临时文件替换核心二进制。
安装器不会:
@@ -52,6 +54,15 @@ sudo ./install-linux.sh --source-dir /tmp/scert-linux-amd64
- 创建公网防火墙规则。
- 删除已有配置、数据库、证书和备份。
如果服务仍在运行,安装器会直接拒绝安装或升级。生产升级必须先创建完整备份,再停止服务:
```bash
sudo systemctl stop Scert
sudo systemctl stop Scert-admin
sudo ./install-linux.sh --source-dir /tmp/scert-linux-amd64
sudo systemctl start Scert
```
## 安装后流程
安装完成后先运行初始化流程,填写超级管理员、邮件、DNS API、端口和证书路径配置。初始化流程负责 DNS API 验证、Web 证书申请、部署校验和主服务端口防火墙处理。
@@ -65,6 +76,31 @@ systemctl stop Scert-admin
`Scert-admin` 不监听任何 TCP/UDP 端口。启动后,它只维护 Scert 主服务 `/reset` 路径的短时激活租约,并将一次性校验码写入 `/run/scert-admin/reset-code` 受保护临时文件,不写入标准输出或 systemd 日志;停止后入口立即失效,异常退出后入口会在租约过期时失效。管理员可使用 `sudo cat /run/scert-admin/reset-code` 读取校验码,校验码在成功消费、服务停止或租约失效后自动销毁。云安全组只需由管理员根据初始化提示放行主服务端口。
### 存活检查与生产就绪检查
Scert 提供两个用途不同的无认证检查接口:
- `GET /healthz`:只表示进程和 HTTP 服务仍可响应,不能证明 DNS 凭据、TLS 文件和数据库可用。
- `GET /readyz`:生产就绪检查,只有初始化完成、已配置的敏感凭据可解密、TLS 证书与私钥为普通文件且数据库可访问时才返回 HTTP `200`。
安装、升级、恢复和配置变更后必须同时检查:
```bash
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
```
`/readyz` 失败时返回 HTTP `503` 和不包含敏感引用的原因码:
- `setup_incomplete`:初始化尚未完成。
- `dns_credential_missing`:DNS 凭据引用为空。
- `secret_store_unavailable`:敏感信息存储未初始化。
- `credential_unavailable`:DNS、HTTP 通知或 SMTP 通知凭据引用不存在或无法解密,必须通过管理页面重新在线测试并保存真实凭据。
- `tls_material_unavailable`:内部 TLS 证书或私钥缺失、不是普通文件或是符号链接。
- `database_unavailable`:数据库不可访问。
禁止写入假 Token 或伪造敏感信息引用来绕过就绪检查。Nginx、监控系统和升级验收应使用 `/readyz` 判断是否可接收生产流量,`/healthz` 仅用于判断进程是否存活。
### 环境变量覆盖
`Scert` 启动时支持使用 `SCERT_*` 环境变量覆盖当前进程配置,适合写入 systemd 的 `EnvironmentFile`。例如:
@@ -87,6 +123,28 @@ Linux 安装目录当前固定为 `/scert`。自定义证书根目录必须是
安装器是文件部署阶段,不负责替代首次初始化向导,也不代替真实 ACME 申请和远程部署验收。
## 生产反向代理要求
生产环境必须让 Scert 只监听回环地址,例如 `127.0.0.1:9004`,由 Nginx 对外监听 `443`。Nginx 到 Scert 的 HTTPS 上游连接必须校验证书,不得使用 `proxy_ssl_verify off`:
```nginx
location / {
proxy_pass https://127.0.0.1:9004;
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_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
}
```
如果内部证书由私有 CA 签发,应将对应 CA 证书保存到仅 root 可修改的独立文件,并配置到 `proxy_ssl_trusted_certificate`。不要通过关闭上游验证规避证书名称或信任链问题。
## 开发阶段反向代理部署
开发阶段可以使用测试域名 `web.xuans.com` 验证 Web 页面和反向代理链路。推荐让 Scert 只监听本机端口 `9004`,由 Nginx 监听 `9003` 接收测试访问并转发:
@@ -125,7 +183,9 @@ server {
proxy_pass https://127.0.0.1:9004;
proxy_ssl_server_name on;
proxy_ssl_name web.xuans.com;
proxy_ssl_verify off;
proxy_ssl_verify on;
proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;
proxy_ssl_verify_depth 3;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
@@ -139,6 +199,30 @@ server {
`web.xuans.com` 仅用于开发阶段测试,不能作为生产环境证书、DNS、ACME 或最终 HTTPS 验收依据。
开发环境使用自签名证书时,应优先将测试 CA 加入独立信任文件。只有在隔离的临时开发环境中,才允许短时使用 `proxy_ssl_verify off`;该设置禁止复制到生产配置。
## 备份与恢复
完整备份包含配置、主密钥、加密敏感配置、SQLite 一致性快照或 MySQL 导出、证书目录以及带 SHA-256 的 `manifest.json`。备份目录必须由 `Scert` 用户控制并保持 `0700`,不得放入 Web 根目录或公开共享目录。
备份和恢复都会获取跨进程维护锁;如果主服务仍在运行会直接拒绝。运维时仍必须显式停服,避免外部工具或尚未纳入锁协议的操作修改证书目录:
```bash
sudo systemctl stop Scert
sudo -u Scert /scert/scert --config /scert/conf/scert.json backup
sudo systemctl start Scert
```
恢复命令:
```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` 副本;恢复失败会尝试回滚配置、数据库、主密钥、敏感配置和证书。备份清单不是数字签名,不能抵抗有权限同时篡改文件并重新生成清单的攻击者,因此备份目录权限和离线副本仍是生产安全边界。
## Windows 部署
Windows 发布目录应包含:
@@ -161,7 +245,7 @@ powershell -ExecutionPolicy Bypass -File .\install-windows.ps1 -SourceDirectory
- 配置和运行数据目录:`C:\ProgramData\Scert`
- 证书目录:`C:\ProgramData\Scert\ssl`
安装器会检查 Windows、管理员权限、`sc.exe`、`icacls.exe` 和两个程序产物;创建配置、数据、日志、备份、文档、运行时和证书目录;设置 Windows ACL;使用 `LocalService` 身份注册 `Scert` 与 `Scert-admin` 服务;并写入不含凭据的安装记录。
安装器会检查 Windows、管理员权限、`sc.exe`、`icacls.exe`、Windows amd64 PE 程序产物、路径重解析点和服务停止状态;创建配置、数据、日志、备份、文档、运行时和证书目录;设置 Windows ACL;使用 `LocalService` 身份注册 `Scert` 与 `Scert-admin` 服务;并写入不含凭据的安装记录。
安装器不会删除或覆盖已有配置、数据库、证书和备份,不会启动或重启服务,也不会创建公网防火墙规则。`Scert` 注册为自动启动,`Scert-admin` 注册为手动启动;只有确需密码重置时才应由管理员启动 `Scert-admin`,完成后立即停止。