补齐Nginx辅助服务安全初始化与部署模板

This commit is contained in:
xuans committed 2026-09-20 02:29:36 +08:00
1 parent aa5d669db1
commit d8b4850916
13 files changed
+593 -4

No files matched your search

+2
View File
@@ -21,6 +21,8 @@ deploy/
二进制文件应针对目标平台构建为 Linux amd64,并且具有可执行权限。
Linux 发布包还包含 `scert-nginx`、`systemd/scert-nginx.socket`、`systemd/scert-nginx.service` 和 `nginx/` 下的策略模板与中文说明。它们是独立、显式安装的管理证书激活组件,普通安装器不安装、不启用、不修改共享 Nginx。接线流程见 [Nginx 辅助服务部署说明](nginx/Nginx辅助服务部署说明.md),需要单独完成实机验证。
## 安装命令
```bash
@@ -0,0 +1,81 @@
# Nginx 辅助服务部署说明
本流程面向 Linux 的 root 维护人员,使用独立 Unix socket 完成管理证书双层切换。普通安装器不会安装或启用辅助服务。本模板尚待目标主机 systemd 与实际 Nginx 配置验证,不代表生产验收已通过。
## 部署前核对
- 先确认 SSH 主机身份、备份及维护窗口。检查目标站点、已有服务、端口、Nginx 主进程用户、二进制、主配置、PID、日志和缓存目录,不修改其他站点。
- 管理域名和公开端口由部署环境指定。策略只接受具体域名与两个不同的回环地址。Scert 应用的域名、代理公开端口、HTTPS 上游端口必须与策略一致。
- 代理和上游必须已提供同一张受系统 CA 信任、覆盖管理域名且未过期的证书,两个 `/readyz` 均成功。初始化不签发证书,不接受自签名证书,不绕过验证。
- 程序、策略、Nginx 主配置及全部 include、模块、PID 和可执行依赖须由 root 维护。不要让应用用户修改这些路径或任何父目录;不能把任意应用用户可写配置交给 root 的 `nginx -t` 或重载命令。
- 使用与核心程序配套的辅助程序版本,先核验发布包 `SHA256SUMS`。辅助程序必须安装在 `/usr/local/libexec/scert-nginx`,不能直接以 root 运行应用可写目录中的程序。
- 停止并禁止管理证书变更任务;首次接线期间两个服务仍须能响应就绪探测。辅助服务尚未接通时,应用的代理续期保护会拒绝新的签发。
## 首次文件安装
先核对以下路径均无符号链接、硬链接、非 root 写权限或既有安装。本节命令仅用于首次安装,不作为升级覆盖命令。目标已存在时停止,检查来源和内容,不删除旧状态。
```sh
install -d -o root -g root -m 0755 /usr/local/libexec
install -d -o root -g root -m 0700 /etc/scert-nginx
install -d -o root -g root -m 0700 /var/lib/scert-nginx
install -d -o root -g root -m 0755 /run/scert-nginx
test ! -e /usr/local/libexec/scert-nginx && test ! -L /usr/local/libexec/scert-nginx &&
install -o root -g root -m 0755 ./scert-nginx /usr/local/libexec/scert-nginx
test ! -e /etc/scert-nginx/policy.json && test ! -L /etc/scert-nginx/policy.json &&
install -o root -g root -m 0600 ./nginx/policy.json.example /etc/scert-nginx/policy.json
id -u Scert
```
使用编辑器填写 `policy.json` 的 `allowed_uid` 为实际非 root 数字 UID,填写域名与现场地址,并核实 Nginx 路径。默认 `allowed_uid=null` 和域名占位符故意不可用,不能原样加载。Nginx 前缀使用规范绝对目录,不带结尾斜杠。应用 socket 固定为 `/run/scert-nginx/activation.sock`,不得改为 TCP。
独立复制当前证书链和私钥到 root 控制的暂存目录,例如 `/etc/scert-nginx/initial/`,目录 0700、文件 0600。先核对实际来源是普通文件、内容属于当前管理证书,再复制;初始化器不直接读取应用用户可写路径或符号链接。不要把密钥内容放入命令行、日志或文档。
```sh
/usr/local/libexec/scert-nginx \
--policy /etc/scert-nginx/policy.json \
--initialize \
--certificate /etc/scert-nginx/initial/fullchain.pem \
--private-key /etc/scert-nginx/initial/key.pem
```
初始化会核对输入权限、可信证书链、代理与上游实际叶证书、就绪响应及当前 `nginx -t`。通过后,在专用目录内生成随机版本子目录及 `active.conf`,私钥和引用为 0600。它不修改站点、不重载 Nginx、不创建轮换事务。目标目录只允许已有锁文件;任何旧版本、事务或失败残留均拒绝覆盖,失败后先检查,不盲目重试或清空目录。
## 站点接线
保留原站点备份,只把当前管理站点的 `ssl_certificate` 和 `ssl_certificate_key` 两行替换为下面的引用,不在同一层保留重复指令:
```nginx
include /var/lib/scert-nginx/active.conf;
```
继续保留 `Scert.conf.example` 的域名、回环 HTTPS 上游、SNI 和 `proxy_ssl_verify on`。root Nginx 主进程可以读取 0700 专用目录,不给工作进程或应用用户开放私钥权限。非 root 主进程不适用本模板,不能靠放宽权限解决。
先执行策略指定的 Nginx 二进制、前缀和主配置的 `-t`,成功后由维护人员单次平滑重载,再严格验证代理和上游证书及 `/readyz`。对公网域名另行验证正常 DNS 与未强制 IP 的浏览器访问;回环探测不代表公网通过。接线失败时按备份恢复原站点并核验,保留专用目录供排查。
## 安装并启用通道
确认 `/etc/systemd/system/scert-nginx.socket`、`.service` 不存在,且 `/run/scert-nginx` 为 root 所有且不可由其他用户写入。安装发布包中的模板,不覆盖既有服务:
```sh
test ! -e /etc/systemd/system/scert-nginx.socket && test ! -L /etc/systemd/system/scert-nginx.socket &&
install -o root -g root -m 0644 ./systemd/scert-nginx.socket /etc/systemd/system/scert-nginx.socket
test ! -e /etc/systemd/system/scert-nginx.service && test ! -L /etc/systemd/system/scert-nginx.service &&
install -o root -g root -m 0644 ./systemd/scert-nginx.service /etc/systemd/system/scert-nginx.service
systemd-analyze verify /etc/systemd/system/scert-nginx.socket /etc/systemd/system/scert-nginx.service
systemctl daemon-reload
systemctl enable --now scert-nginx.socket
systemctl status scert-nginx.socket --no-pager
```
服务由 socket 激活,不设置应用的 sudo、root 用户或额外能力。socket 为 root 所有、Scert 组、0660;服务还以内核对端 UID 核对策略中的唯一调用者。运行目录由 socket 创建,服务停止不移除它,不借用应用所有的 `RuntimeDirectory`。
模板对文件系统只读,仅开放专用状态目录及常见 Nginx 日志、缓存和已有 PID 文件。`CAP_DAC_OVERRIDE` 用于读取可信配置引用的受限材料以及打开工作用户所有的 Nginx 日志,`CAP_CHOWN` 用于 Nginx 配置检查中的路径所有者检查;写入仍受只读挂载及上述有限可写路径约束。辅助服务依赖 `nginx.service`,随其停止或重启,以便重建 PID 文件的隔离挂载;现场 Nginx 单元名不同时须同步调整 `Requires`、`After` 和 `PartOf`。非标准日志、缓存或 PID 路径须按现场最小范围评审 drop-in,不能直接放开 `/etc`、`/run` 或整个文件系统。不要使用私有网络命名空间,否则无法探测正式回环上游。
先完成隔离 systemd 测试,再验证真实调用 UID、非授权 UID 拒绝、辅助服务重启、主机重启、证书轮换、故障恢复和其他站点不受影响。仅有 socket 活跃、`nginx -t` 或核心 `/readyz` 成功都不等于双层协调验收。当前应用尚无独立管理协调就绪命令,完整流程仍须通过实际续期任务和两层证书证据核对。
## 升级与恢复
升级前等待应用协调与辅助事务均结束,停止相关变更任务,再停止 socket 和辅助服务。检查它们均已停止后才替换 root 所有的辅助程序,保留旧程序及校验摘要;不重复初始化、不清空版本或请求记录,重新启动 socket 后复验。
辅助程序状态与应用协调记录必须成套备份。现有应用完整备份不包含 `/etc/scert-nginx`、`/var/lib/scert-nginx` 和 Nginx 站点配置,不能声称只恢复应用备份就完成双层灾难恢复。停止变更并核对终态后,另行备份这些 root 文件、服务模板与 include 依赖;恢复时核对 UID、策略、应用证书路径、两层实际证书和事务记录一致。任何未决或损坏记录均保持保护,交由维护人员检查,不通过删除记录解除保护。
+12
View File
@@ -0,0 +1,12 @@
{
"version": 1,
"allowed_uid": null,
"socket_path": "/run/scert-nginx/activation.sock",
"directory": "/var/lib/scert-nginx",
"hostname": "__MANAGEMENT_HOST__",
"proxy_address": "127.0.0.1:443",
"upstream_address": "127.0.0.1:9004",
"nginx_binary": "/usr/sbin/nginx",
"nginx_config": "/etc/nginx/nginx.conf",
"nginx_prefix": "/etc/nginx"
}
+38
View File
@@ -0,0 +1,38 @@
[Unit]
Description=Scert Nginx 受限证书激活服务
Requires=scert-nginx.socket nginx.service
PartOf=nginx.service
After=scert-nginx.socket nginx.service
ConditionPathExists=/etc/scert-nginx/policy.json
[Service]
Type=simple
User=root
Group=root
ExecStart=/usr/local/libexec/scert-nginx --policy /etc/scert-nginx/policy.json
UMask=0077
TimeoutStopSec=40
Restart=on-failure
RestartSec=5
NoNewPrivileges=yes
CapabilityBoundingSet=CAP_DAC_OVERRIDE CAP_CHOWN
AmbientCapabilities=
PrivateTmp=yes
PrivateDevices=yes
ProtectSystem=strict
ProtectHome=yes
ProtectHostname=yes
ProtectClock=yes
ProtectKernelTunables=yes
ProtectKernelModules=yes
ProtectKernelLogs=yes
ProtectControlGroups=yes
LockPersonality=yes
MemoryDenyWriteExecute=yes
RestrictNamespaces=yes
RestrictRealtime=yes
RestrictSUIDSGID=yes
SystemCallArchitectures=native
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
# Nginx 配置检查会打开日志和 PID;非标准部署须按实际路径单独评审。
ReadWritePaths=/var/lib/scert-nginx -/var/log/nginx -/var/lib/nginx -/var/cache/nginx -/run/nginx.pid
+15
View File
@@ -0,0 +1,15 @@
[Unit]
Description=Scert Nginx 本地激活通道
[Socket]
ListenStream=/run/scert-nginx/activation.sock
Accept=no
SocketUser=root
SocketGroup=Scert
SocketMode=0660
DirectoryMode=0755
RemoveOnStop=no
Service=scert-nginx.service
[Install]
WantedBy=sockets.target