生产部署整改阶段检查点

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`,完成后立即停止。
+61 -15
View File
@@ -12,6 +12,7 @@ readonly INSTALL_METADATA_FILE="$INSTALL_DIR/conf/installation.json"
source_dir="$SCRIPT_DIR"
certificate_dir="$DEFAULT_CERTIFICATE_DIR"
certificate_dir_explicit=false
nologin_shell=""
print_usage() {
@@ -48,6 +49,7 @@ parse_args() {
--certificate-dir)
(($# >= 2)) || fail "--certificate-dir 缺少参数"
certificate_dir="$2"
certificate_dir_explicit=true
shift 2
;;
-h|--help)
@@ -61,6 +63,25 @@ parse_args() {
done
}
load_existing_certificate_dir() {
if [[ "$certificate_dir_explicit" == "true" || ! -e "$INSTALL_METADATA_FILE" ]]; then
return
fi
reject_symlink_path "$INSTALL_METADATA_FILE" "安装路径记录"
[[ -f "$INSTALL_METADATA_FILE" ]] || fail "安装路径记录必须是普通文件:$INSTALL_METADATA_FILE"
local line
local existing_certificate_dir=""
while IFS= read -r line; do
if [[ "$line" =~ \"certificate_root\"[[:space:]]*:[[:space:]]*\"([^\"]+)\" ]]; then
existing_certificate_dir="${BASH_REMATCH[1]}"
break
fi
done < "$INSTALL_METADATA_FILE"
[[ -n "$existing_certificate_dir" ]] || fail "无法从既有安装记录读取证书目录,请显式使用 --certificate-dir"
certificate_dir="$existing_certificate_dir"
}
validate_certificate_dir() {
[[ "$certificate_dir" == /* ]] || fail "证书目录必须是绝对路径"
[[ "$certificate_dir" != "/" ]] || fail "证书目录不能是根目录"
@@ -131,28 +152,44 @@ validate_environment() {
[[ "$(uname -s)" == "Linux" ]] || fail "此安装器只支持 Linux"
[[ "$(id -u)" -eq 0 ]] || fail "请使用 root 或 sudo 运行安装器"
local command_name
for command_name in install systemctl getent groupadd useradd id chmod chown cut grep readlink find; do
for command_name in install systemctl getent groupadd useradd id chmod chown cut grep readlink find file mv cp rm; do
command -v "$command_name" >/dev/null 2>&1 || fail "找不到系统命令:$command_name"
done
nologin_shell="$(command -v nologin || true)"
[[ -n "$nologin_shell" ]] || fail "找不到 nologin,无法创建禁止登录的服务用户"
load_existing_certificate_dir
validate_certificate_dir
validate_managed_paths
}
validate_artifacts() {
[[ -d "$source_dir" ]] || fail "安装产物目录不存在:$source_dir"
source_dir="$(cd -- "$source_dir" && pwd)"
source_dir="$(cd -- "$source_dir" && pwd -P)"
local artifact
for artifact in scert scert-admin; do
[[ -f "$source_dir/$artifact" ]] || fail "安装产物不存在:$source_dir/$artifact"
[[ -r "$source_dir/$artifact" ]] || fail "安装产物不可执行:$source_dir/$artifact"
[[ -f "$source_dir/$artifact" && ! -L "$source_dir/$artifact" ]] || fail "安装产物必须是普通文件:$source_dir/$artifact"
[[ -r "$source_dir/$artifact" && -x "$source_dir/$artifact" ]] || fail "安装产物不可读取或执行:$source_dir/$artifact"
local artifact_description
artifact_description="$(LC_ALL=C file -b -- "$source_dir/$artifact")"
[[ "$artifact_description" == *"ELF 64-bit LSB"* && "$artifact_description" == *"x86-64"* ]] || \
fail "安装产物不是 Linux amd64 ELF:$source_dir/$artifact"
done
[[ -f "$source_dir/web/index.html" ]] || fail "缺少前端入口文件:$source_dir/web/index.html"
[[ -f "$SCRIPT_DIR/systemd/Scert.service" ]] || fail "缺少 Scert systemd unit"
[[ -f "$SCRIPT_DIR/systemd/Scert-admin.service" ]] || fail "缺少 Scert-admin systemd unit"
[[ -f "$SCRIPT_DIR/systemd/Scert-admin服务管理说明.md" ]] || fail "缺少 Scert-admin 服务管理说明"
[[ -f "$SCRIPT_DIR/systemd/Scert服务管理说明.md" ]] || fail "缺少 Scert 服务管理说明"
[[ -f "$source_dir/web/index.html" && ! -L "$source_dir/web/index.html" ]] || fail "缺少普通前端入口文件:$source_dir/web/index.html"
[[ -z "$(find "$source_dir/web" -type l -print -quit)" ]] || fail "Web 安装产物不能包含符号链接"
[[ -z "$(find "$source_dir/web" ! -type f ! -type d -print -quit)" ]] || fail "Web 安装产物包含不支持的特殊文件"
[[ -f "$SCRIPT_DIR/systemd/Scert.service" && ! -L "$SCRIPT_DIR/systemd/Scert.service" ]] || fail "缺少普通 Scert systemd unit"
[[ -f "$SCRIPT_DIR/systemd/Scert-admin.service" && ! -L "$SCRIPT_DIR/systemd/Scert-admin.service" ]] || fail "缺少普通 Scert-admin systemd unit"
[[ -f "$SCRIPT_DIR/systemd/Scert-admin服务管理说明.md" && ! -L "$SCRIPT_DIR/systemd/Scert-admin服务管理说明.md" ]] || fail "缺少普通 Scert-admin 服务管理说明"
[[ -f "$SCRIPT_DIR/systemd/Scert服务管理说明.md" && ! -L "$SCRIPT_DIR/systemd/Scert服务管理说明.md" ]] || fail "缺少普通 Scert 服务管理说明"
}
ensure_services_stopped() {
if systemctl is-active --quiet Scert.service; then
fail "升级或安装前必须停止 Scert.service"
fi
if systemctl is-active --quiet Scert-admin.service; then
fail "升级或安装前必须停止 Scert-admin.service"
fi
}
ensure_service_account() {
@@ -210,19 +247,27 @@ create_directories() {
}
write_install_metadata() {
printf '{\n "certificate_root": "%s"\n}\n' "$certificate_dir" > "$INSTALL_METADATA_FILE"
chown root:"$SERVICE_GROUP" "$INSTALL_METADATA_FILE"
chmod 0640 "$INSTALL_METADATA_FILE"
local temporary_file="$INSTALL_METADATA_FILE.new.$$"
printf '{\n "certificate_root": "%s"\n}\n' "$certificate_dir" > "$temporary_file"
chown root:"$SERVICE_GROUP" "$temporary_file"
chmod 0640 "$temporary_file"
mv -f -- "$temporary_file" "$INSTALL_METADATA_FILE"
}
install_binaries() {
install -o root -g root -m 0755 "$source_dir/scert" "$INSTALL_DIR/scert"
install -o root -g root -m 0755 "$source_dir/scert-admin" "$INSTALL_DIR/scert-admin"
local main_temporary="$INSTALL_DIR/.scert.new.$$"
local admin_temporary="$INSTALL_DIR/.scert-admin.new.$$"
install -o root -g root -m 0755 "$source_dir/scert" "$main_temporary"
install -o root -g root -m 0755 "$source_dir/scert-admin" "$admin_temporary"
mv -f -- "$main_temporary" "$INSTALL_DIR/scert"
mv -f -- "$admin_temporary" "$INSTALL_DIR/scert-admin"
}
install_web() {
[[ -z "$(find "$INSTALL_DIR/web" -type l -print -quit)" ]] || fail "既有 Web 目录包含符号链接,拒绝覆盖"
[[ -z "$(find "$INSTALL_DIR/web" ! -type f ! -type d -print -quit)" ]] || fail "既有 Web 目录包含不支持的特殊文件"
cp -a "$source_dir/web/." "$INSTALL_DIR/web/"
find "$INSTALL_DIR/web" -type d -exec chmod 0755 {} +
find "$INSTALL_DIR/web" -type d -exec chown root:root {} + -exec chmod 0755 {} +
find "$INSTALL_DIR/web" -type f -exec chown root:root {} + -exec chmod 0644 {} +
}
@@ -274,6 +319,7 @@ main() {
parse_args "$@"
validate_environment
validate_artifacts
ensure_services_stopped
ensure_service_account
create_directories
write_install_metadata
+75 -1
View File
@@ -43,6 +43,69 @@ function Resolve-RequiredDirectory {
return $resolved.TrimEnd([System.IO.Path]::DirectorySeparatorChar)
}
function Assert-NoReparsePoint {
param(
[Parameter(Mandatory = $true)]
[string]$Path,
[Parameter(Mandatory = $true)]
[string]$Label
)
$resolved = [System.IO.Path]::GetFullPath($Path)
$root = [System.IO.Path]::GetPathRoot($resolved)
$current = $root
$relative = $resolved.Substring($root.Length)
foreach ($segment in $relative.Split([System.IO.Path]::DirectorySeparatorChar, [System.StringSplitOptions]::RemoveEmptyEntries)) {
$current = Join-Path $current $segment
if (Test-Path -LiteralPath $current) {
$item = Get-Item -LiteralPath $current -Force
if (($item.Attributes -band [System.IO.FileAttributes]::ReparsePoint) -ne 0) {
throw "$Label 不能包含重解析点或符号链接:$current"
}
}
}
}
function Assert-ServiceStopped {
param(
[Parameter(Mandatory = $true)]
[string]$Name
)
$service = Get-Service -Name $Name -ErrorAction SilentlyContinue
if ($null -ne $service -and $service.Status -ne [System.ServiceProcess.ServiceControllerStatus]::Stopped) {
throw "升级或安装前必须停止 Windows 服务:$Name"
}
}
function Assert-WindowsAmd64Executable {
param(
[Parameter(Mandatory = $true)]
[string]$Path
)
$stream = [System.IO.File]::OpenRead($Path)
$reader = [System.IO.BinaryReader]::new($stream)
try {
if ($stream.Length -lt 64 -or $reader.ReadUInt16() -ne 0x5A4D) {
throw "安装产物不是有效的 Windows PE 文件:$Path"
}
$stream.Position = 0x3C
$peOffset = $reader.ReadInt32()
if ($peOffset -lt 0 -or ($peOffset + 6) -gt $stream.Length) {
throw "安装产物的 PE 头无效:$Path"
}
$stream.Position = $peOffset
if ($reader.ReadUInt32() -ne 0x00004550 -or $reader.ReadUInt16() -ne 0x8664) {
throw "安装产物不是 Windows amd64 可执行文件:$Path"
}
}
finally {
$reader.Dispose()
$stream.Dispose()
}
}
function Invoke-Sc {
param(
[Parameter(Mandatory = $true)]
@@ -115,6 +178,13 @@ $install = Resolve-RequiredDirectory -Path $InstallDirectory -Label "程序安
$data = Resolve-RequiredDirectory -Path $DataDirectory -Label "数据目录"
$certificate = Resolve-RequiredDirectory -Path $CertificateDirectory -Label "证书目录"
Assert-NoReparsePoint -Path $source -Label "安装产物目录"
Assert-NoReparsePoint -Path $install -Label "程序安装目录"
Assert-NoReparsePoint -Path $data -Label "数据目录"
Assert-NoReparsePoint -Path $certificate -Label "证书目录"
Assert-ServiceStopped -Name $ServiceName
Assert-ServiceStopped -Name $AdminServiceName
$sourceScert = Join-Path $source "scert.exe"
$sourceAdmin = Join-Path $source "scert-admin.exe"
if (-not (Test-Path -LiteralPath $sourceScert -PathType Leaf)) {
@@ -123,6 +193,10 @@ if (-not (Test-Path -LiteralPath $sourceScert -PathType Leaf)) {
if (-not (Test-Path -LiteralPath $sourceAdmin -PathType Leaf)) {
throw "安装产物目录缺少 scert-admin.exe:$sourceAdmin"
}
Assert-NoReparsePoint -Path $sourceScert -Label "Scert 安装产物"
Assert-NoReparsePoint -Path $sourceAdmin -Label "Scert-admin 安装产物"
Assert-WindowsAmd64Executable -Path $sourceScert
Assert-WindowsAmd64Executable -Path $sourceAdmin
$configDirectory = Join-Path $data "config"
$databaseDirectory = Join-Path $data "data"
@@ -189,4 +263,4 @@ Write-Host "证书目录:$certificate"
Write-Host "安装记录:$metadataPath"
Write-Host "Scert 主服务已注册为自动启动,但本安装器没有启动或重启服务。"
Write-Host "Scert-admin 已注册为手动启动,本安装器不会启动它,也不会创建公网防火墙规则。"
Write-Host "首次初始化时请使用配置文件路径:$configurationPath"
Write-Host "首次初始化时请使用配置文件路径:$configurationPath"
+18 -1
View File
@@ -19,9 +19,26 @@ Restart=no
RuntimeMaxSec=30min
UMask=0077
NoNewPrivileges=yes
CapabilityBoundingSet=
AmbientCapabilities=
PrivateTmp=yes
PrivateDevices=yes
PrivateNetwork=yes
ProtectHome=yes
ProtectSystem=full
ProtectSystem=strict
ProtectHostname=yes
ProtectClock=yes
ProtectKernelTunables=yes
ProtectKernelModules=yes
ProtectControlGroups=yes
ProtectKernelLogs=yes
LockPersonality=yes
MemoryDenyWriteExecute=yes
RestrictNamespaces=yes
RestrictRealtime=yes
RestrictSUIDSGID=yes
RemoveIPC=yes
SystemCallArchitectures=native
ReadWritePaths=/scert/data /scert/log /run/scert-admin
RestrictAddressFamilies=AF_UNIX
+17 -1
View File
@@ -16,9 +16,25 @@ TimeoutStopSec=30
Restart=on-failure
UMask=0077
NoNewPrivileges=yes
CapabilityBoundingSet=
AmbientCapabilities=
PrivateTmp=yes
PrivateDevices=yes
ProtectHome=yes
ProtectSystem=full
ProtectSystem=strict
ProtectHostname=yes
ProtectClock=yes
ProtectKernelTunables=yes
ProtectKernelModules=yes
ProtectControlGroups=yes
ProtectKernelLogs=yes
LockPersonality=yes
MemoryDenyWriteExecute=yes
RestrictNamespaces=yes
RestrictRealtime=yes
RestrictSUIDSGID=yes
RemoveIPC=yes
SystemCallArchitectures=native
ReadWritePaths=/ssl /scert/conf /scert/data /scert/log /scert/backups
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6