补齐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

@@ -36,6 +36,8 @@
## 接入前要求
发布包现提供独立 socket/service、拒绝直接使用的策略模板和 `--initialize` 命令。初始化从 root 受保护副本导入当前证书,核对双层 TLS 与就绪状态,仅创建专用材料,不修改或重载站点;已有状态或失败残留拒绝覆盖。部署步骤见 `deploy/nginx/Nginx辅助服务部署说明.md`,新增初始化用例尚待 Linux 执行,模板尚未完成 systemd 实机验收。
1. 安装独立 socket/service,固定调用 UID,初始化专用版本目录并让目标站点引用 `active.conf`。
2. 应用须持久化旧状态、候选摘要、激活阶段和关联事务;完整生命周期必须串行化,不能在恢复检查上游之后并发切换上游。
3. 覆盖代理暂存、上游配置持久化与内存切换、代理提交之间的中断及应答丢失,并在启动时先恢复再允许申请下一张证书。
@@ -0,0 +1,121 @@
package nginxactivation
import (
"context"
"errors"
"fmt"
"os"
"path/filepath"
)
// Initialize 仅准备首次接线材料,不修改站点、不重载 Nginx,也不覆盖已有状态。
func (r Rotation) Initialize(ctx context.Context, certificatePath, privateKeyPath string) (string, error) {
root, lock, err := r.open(ctx)
if err != nil {
return "", err
}
defer root.Close()
defer lock.Close()
if err := requireUninitialized(root); err != nil {
return "", err
}
chain, err := readInitializationMaterial(certificatePath, 1<<20, false)
if err != nil {
return "", err
}
key, err := readInitializationMaterial(privateKeyPath, 64<<10, true)
if err != nil {
return "", err
}
defer clear(key)
leaf, err := r.validateMaterial(ctx, chain, key)
if err != nil {
return "", err
}
if err := r.Proxy.Wait(ctx, leaf.Raw); err != nil {
return "", err
}
if err := r.Upstream.Wait(ctx, leaf.Raw); err != nil {
return "", err
}
if err := r.Reloader.Check(ctx); err != nil {
return "", fmt.Errorf("初始化前 Nginx 配置检查失败:%w", err)
}
if err := ctx.Err(); err != nil {
return "", err
}
if err := requireUninitialized(root); err != nil {
return "", err
}
id, err := newID()
if err != nil {
return "", err
}
if err := root.Mkdir(id, 0o700); err != nil {
return "", err
}
if err := writeExclusive(root, filepath.Join(id, "fullchain.pem"), chain); err != nil {
return "", err
}
if err := writeExclusive(root, filepath.Join(id, "key.pem"), key); err != nil {
return "", err
}
version, err := root.Open(id)
if err != nil {
return "", err
}
if err := errors.Join(version.Sync(), version.Close()); err != nil {
return "", err
}
// 最后独占创建引用;断电或写入失败后的残留必须人工核对,不能自动覆盖重试。
if err := writeExclusive(root, includeName, renderInclude(r.Directory, id)); err != nil {
return "", err
}
directory, err := root.Open(".")
if err != nil {
return "", err
}
if err := errors.Join(directory.Sync(), directory.Close()); err != nil {
return "", err
}
return id, nil
}
func requireUninitialized(root *os.Root) error {
directory, err := root.Open(".")
if err != nil {
return err
}
defer directory.Close()
entries, err := directory.ReadDir(-1)
if err != nil {
return err
}
for _, entry := range entries {
if entry.Name() != ".activation.lock" {
return errors.New("激活目录存在旧状态或初始化残留,拒绝覆盖,请先人工核对")
}
}
return nil
}
func readInitializationMaterial(path string, limit int64, private bool) ([]byte, error) {
if err := validateOwnedFile(path, uint32(os.Geteuid()), false); err != nil {
return nil, err
}
root, err := os.OpenRoot(filepath.Dir(path))
if err != nil {
return nil, err
}
defer root.Close()
if private {
info, err := root.Lstat(filepath.Base(path))
if err != nil {
return nil, err
}
if info.Mode().Perm()&0o077 != 0 {
return nil, errors.New("初始化私钥不能允许组或其他用户读取")
}
}
return readRegular(root, filepath.Base(path), limit)
}
@@ -0,0 +1,189 @@
package nginxactivation
import (
"bytes"
"context"
"errors"
"os"
"path/filepath"
"testing"
"time"
"git.pcux.cn/xuans/Scert/backend/internal/processlock"
"golang.org/x/sys/unix"
)
func initializationFixture(t *testing.T) (*rotationFixture, string, string) {
t.Helper()
f := newRotationFixture(t)
f.rotation.Directory = t.TempDir()
if err := os.Chmod(f.rotation.Directory, 0o700); err != nil {
t.Fatal(err)
}
material := t.TempDir()
chain, key := filepath.Join(material, "fullchain.pem"), filepath.Join(material, "key.pem")
writeTestFile(t, chain, f.old.chain)
writeTestFile(t, key, f.old.key)
return f, chain, key
}
func TestInitializeCreatesPrivateBaselineWithoutReload(t *testing.T) {
f, chain, key := initializationFixture(t)
ctx, cancel := context.WithTimeout(t.Context(), 5*time.Second)
defer cancel()
id, err := f.rotation.Initialize(ctx, chain, key)
if err != nil || !validID(id) {
t.Fatal("初始化失败或版本编号无效", err)
}
if f.reloader.reloadCount != 0 || f.reloader.checkCount != 1 {
t.Fatal("初始化只能检查既有配置,不能重载")
}
for path, mode := range map[string]os.FileMode{
id: 0o700, filepath.Join(id, "fullchain.pem"): 0o600,
filepath.Join(id, "key.pem"): 0o600, includeName: 0o600,
} {
info, err := os.Lstat(filepath.Join(f.rotation.Directory, path))
if err != nil || info.Mode().Perm() != mode {
t.Fatalf("初始化材料权限错误:%s,%v", path, err)
}
}
root, err := os.OpenRoot(f.rotation.Directory)
if err != nil {
t.Fatal(err)
}
defer root.Close()
include, err := readRegular(root, includeName, 4096)
if err != nil || !bytes.Equal(include, renderInclude(f.rotation.Directory, id)) {
t.Fatal("专用引用格式错误", err)
}
if err := verifyIncludeMaterial(root, include, f.old.pair.Certificate[0]); err != nil {
t.Fatal(err)
}
if _, err := os.Stat(filepath.Join(f.rotation.Directory, journalName)); !errors.Is(err, os.ErrNotExist) {
t.Fatal("初始化不应创建轮换事务", err)
}
if _, err := f.rotation.Initialize(ctx, chain, key); err == nil {
t.Fatal("不能重复初始化已有状态")
}
if err := requireInclude(root, include); err != nil {
t.Fatal("重复初始化改变了原引用", err)
}
}
func TestInitializeRejectsUnsafeMaterial(t *testing.T) {
for _, scenario := range []string{
"key-readable", "key-writable", "parent-writable", "symlink", "hardlink", "fifo",
"large", "mismatch", "different-leaf", "upstream-mismatch", "relative", "missing",
} {
t.Run(scenario, func(t *testing.T) {
f, chain, key := initializationFixture(t)
switch scenario {
case "key-readable", "key-writable", "parent-writable":
path, mode := key, os.FileMode(0o644)
if scenario == "key-writable" {
mode = 0o666
}
if scenario == "parent-writable" {
path, mode = filepath.Dir(key), 0o777
}
if err := os.Chmod(path, mode); err != nil {
t.Fatal(err)
}
case "symlink":
if err := os.Symlink(key, key+".link"); err != nil {
t.Fatal(err)
}
key += ".link"
case "hardlink":
if err := os.Link(key, key+".link"); err != nil {
t.Fatal(err)
}
case "fifo":
key += ".fifo"
if err := unix.Mkfifo(key, 0o600); err != nil {
t.Fatal(err)
}
case "large":
writeTestFile(t, chain, make([]byte, (1<<20)+1))
case "mismatch":
writeTestFile(t, key, f.candidate.key)
case "different-leaf":
writeTestFile(t, chain, f.candidate.chain)
writeTestFile(t, key, f.candidate.key)
case "upstream-mismatch":
f.upstream.active.Store(&f.candidate.pair)
case "relative":
key = "key.pem"
case "missing":
key += ".missing"
}
ctx, cancel := context.WithTimeout(t.Context(), time.Second)
defer cancel()
if _, err := f.rotation.Initialize(ctx, chain, key); err == nil {
t.Fatal("不应接受不可信或不一致的初始化材料")
}
if f.reloader.checkCount != 0 || f.reloader.reloadCount != 0 {
t.Fatal("材料预检失败不应执行 Nginx 命令")
}
assertInitializationEmpty(t, f.rotation.Directory)
})
}
}
func TestInitializePreservesExistingState(t *testing.T) {
for _, scenario := range []string{"include", "transaction", "partial", "external-change", "config-failure", "cancel", "locked"} {
t.Run(scenario, func(t *testing.T) {
f, chain, key := initializationFixture(t)
ctx, cancel := context.WithTimeout(t.Context(), 5*time.Second)
defer cancel()
name, content := "", []byte("保留原有状态\n")
switch scenario {
case "include", "transaction", "partial":
name = map[string]string{"include": includeName, "transaction": journalName, "partial": ".pending-old"}[scenario]
writeTestFile(t, filepath.Join(f.rotation.Directory, name), content)
case "external-change":
name = includeName
f.reloader.check = func(int) error {
writeTestFile(t, filepath.Join(f.rotation.Directory, name), content)
return nil
}
case "config-failure":
f.reloader.check = func(int) error { return errors.New("注入配置检查失败") }
case "cancel":
cancel()
case "locked":
lock, err := processlock.Acquire(filepath.Join(f.rotation.Directory, ".activation.lock"))
if err != nil {
t.Fatal(err)
}
defer lock.Close()
}
if _, err := f.rotation.Initialize(ctx, chain, key); err == nil {
t.Fatal("已有状态、取消或故障不应初始化成功")
}
if f.reloader.reloadCount != 0 {
t.Fatal("初始化不能重载 Nginx")
}
if name == "" {
assertInitializationEmpty(t, f.rotation.Directory)
return
}
actual, err := os.ReadFile(filepath.Join(f.rotation.Directory, name))
if err != nil || !bytes.Equal(actual, content) {
t.Fatal("初始化不能覆盖已有状态", err)
}
})
}
}
func assertInitializationEmpty(t *testing.T, directory string) {
t.Helper()
root, err := os.OpenRoot(directory)
if err != nil {
t.Fatal(err)
}
defer root.Close()
if err := requireUninitialized(root); err != nil {
t.Fatal("预检失败不应留下证书或引用", err)
}
}