refactor: use nginx -s reload instead of systemd

- doc: add comment

internal/backendupdate/operations.go

@@ -20,13 +20,21 @@ import (
 	"yms-daemon/internal/transaction"
 )
 
+// gatewayOperation 切换宿主 Nginx 后端上游的事务操作。Apply 应用 after 快照
+// 并写入回执，Inspect 通过对比当前配置与 before/after 快照判断执行状态。
 type gatewayOperation struct {
-	controller  gatewayController
-	before      hostnginx.Snapshot
-	after       hostnginx.Snapshot
+	// controller 宿主 Nginx 配置的读取与应用控制器。
+	controller gatewayController
+	// before 切换前的 Nginx 配置快照。
+	before hostnginx.Snapshot
+	// after 切换后的 Nginx 配置快照。
+	after hostnginx.Snapshot
+	// receiptPath 切换成功后写入回执摘要的文件路径。
 	receiptPath string
 }
 
+// Apply 应用 after 快照到宿主 Nginx，并在成功后写入摘要回执文件。
+// 回执文件用于 Inspect 区分“已应用”与“应用内容不一致”等状态。
 func (o *gatewayOperation) Apply(ctx context.Context) error {
 	if err := o.controller.Apply(ctx, o.after); err != nil {
 		return err
@@ -34,6 +42,9 @@ func (o *gatewayOperation) Apply(ctx context.Context) error {
 	return writeImmutableFile(o.receiptPath, []byte(snapshotDigest(o.after)), 0o600)
 }
 
+// Inspect 读取当前 Nginx 配置并与 after/before 快照对比，返回该操作是否已应用、
+// 未应用或状态未知。对比同时校验端口与配置内容；回执文件的存在与摘要一致用于
+// 强化“已应用”判定。
 func (o *gatewayOperation) Inspect(context.Context) (transaction.Inspection, error) {
 	current, err := o.controller.Read()
 	if err != nil {
@@ -58,16 +69,23 @@ func (o *gatewayOperation) Inspect(context.Context) (transaction.Inspection, err
 	return transaction.Inspection{Status: transaction.InspectionUnknown, Result: gatewayResult(current)}, nil
 }
 
+// pathOperation 将某文件系统路径调整到期望状态的事务操作。before 保存操作前
+// 的路径状态，desired 保存期望达到的路径状态，Inspect 据此判断执行结果。
 type pathOperation struct {
-	path    string
-	before  pathState
+	// path 被操作的路径。
+	path string
+	// before 操作前的路径状态，用于判断“未应用”。
+	before pathState
+	// desired 期望达到的路径状态，用于判断“已应用”。
 	desired pathState
 }
 
+// Apply 将目标路径调整到 desired 状态。
 func (o *pathOperation) Apply(context.Context) error {
 	return applyPathState(o.path, o.desired)
 }
 
+// Inspect 判断路径当前是否已匹配 desired 或仍匹配 before，返回相应的执行状态。
 func (o *pathOperation) Inspect(context.Context) (transaction.Inspection, error) {
 	desired, err := pathMatches(o.path, o.desired)
 	if err != nil {
@@ -86,15 +104,22 @@ func (o *pathOperation) Inspect(context.Context) (transaction.Inspection, error)
 	return transaction.Inspection{Status: transaction.InspectionUnknown}, nil
 }
 
+// unitStopOperation 停止某个 systemd 单元的事务操作。
 type unitStopOperation struct {
+	// units systemd 管理器。
 	units systemd.Manager
-	name  string
+	// name 待停止的单元名。
+	name string
 }
 
+// Apply 停止指定 systemd 单元。
 func (o *unitStopOperation) Apply(ctx context.Context) error {
 	return o.units.Stop(ctx, o.name)
 }
 
+// Inspect 查询单元状态并判断是否已停止。inactive 与 failed 均视为已停止，因为
+// systemd 可能把成功停止的遗留服务标记为 failed（其追踪的 JVM 以 SIGTERM 退出，
+// 状态码 143），二者都表示已无活动进程，即本步骤所需结果。
 func (o *unitStopOperation) Inspect(ctx context.Context) (transaction.Inspection, error) {
 	unit, err := o.units.Inspect(ctx, o.name)
 	if err != nil {
@@ -116,6 +141,9 @@ func (o *unitStopOperation) Inspect(ctx context.Context) (transaction.Inspection
 	return transaction.Inspection{Status: transaction.InspectionUnknown, Result: result}, nil
 }
 
+// snapshotPath 检查指定路径并把其当前状态快照为 pathState。若路径不存在则返回
+// absent 状态；若为符号链接则记录其目标；若为普通文件则复制一份备份并记录其
+// 尺寸与摘要身份，便于后续校验与恢复。
 func snapshotPath(path string, backupPath string) (pathState, error) {
 	info, err := os.Lstat(path)
 	if errors.Is(err, os.ErrNotExist) {
@@ -141,6 +169,9 @@ func snapshotPath(path string, backupPath string) (pathState, error) {
 	return pathState{Kind: pathKindRegular, BackupPath: backupPath, Identity: identity, Mode: uint32(info.Mode().Perm())}, nil
 }
 
+// applyPathState 将目标路径调整到指定状态：absent 则删除，symlink 则原子地替换
+// 为指向目标的新链接，regular 则校验备份后原子地恢复为普通文件。父目录必须是
+// 直接目录。所有变更完成后都会同步父目录以确保持久化。
 func applyPathState(path string, state pathState) error {
 	parent := filepath.Dir(path)
 	info, err := os.Lstat(parent)
@@ -179,6 +210,9 @@ func applyPathState(path string, state pathState) error {
 	}
 }
 
+// pathMatches 判断路径当前是否匹配指定状态：absent 状态要求路径不存在，symlink
+// 状态要求为指向相同目标的符号链接，regular 状态要求为权限位与身份摘要都一致的
+// 普通文件。
 func pathMatches(path string, state pathState) (bool, error) {
 	info, err := os.Lstat(path)
 	if errors.Is(err, os.ErrNotExist) {
@@ -209,6 +243,8 @@ func pathMatches(path string, state pathState) (bool, error) {
 	}
 }
 
+// copyFileSnapshot 将源文件复制到目标路径并返回其尺寸与 SHA-256 身份信息。
+// 复制采用先写临时文件、同步、再原子重命名的流程，并同步父目录，保证落盘一致。
 func copyFileSnapshot(sourcePath string, destinationPath string, mode os.FileMode) (filestore.Identity, error) {
 	if err := os.MkdirAll(filepath.Dir(destinationPath), 0o750); err != nil {
 		return filestore.Identity{}, err
@@ -250,6 +286,8 @@ func copyFileSnapshot(sourcePath string, destinationPath string, mode os.FileMod
 	return filestore.Identity{Size: size, SHA256: hex.EncodeToString(digest.Sum(nil))}, nil
 }
 
+// copyFileAtomic 原子地将源文件复制到目标路径：先写入同目录临时文件，同步并
+// 关闭后再重命名，最后同步父目录。用于普通文件路径状态的恢复。
 func copyFileAtomic(sourcePath string, destinationPath string, mode os.FileMode) error {
 	source, err := os.Open(sourcePath)
 	if err != nil {
@@ -284,6 +322,9 @@ func copyFileAtomic(sourcePath string, destinationPath string, mode os.FileMode)
 	return syncDirectory(parent)
 }
 
+// writeImmutableFile 以排他方式写入不可变文件：若路径已存在则要求其内容与待写
+// 内容完全一致，否则报错；若不存在则以指定权限原子地创建并同步。写入失败时会
+// 清理残留文件。
 func writeImmutableFile(path string, content []byte, mode os.FileMode) error {
 	if err := os.MkdirAll(filepath.Dir(path), 0o750); err != nil {
 		return err
@@ -326,6 +367,8 @@ func writeImmutableFile(path string, content []byte, mode os.FileMode) error {
 	return nil
 }
 
+// readGatewaySnapshot 读取持久化的 Nginx 配置快照文件，并校验其中活动端口与
+// 期望端口一致，返回快照内容与端口。
 func readGatewaySnapshot(path string, port int) (hostnginx.Snapshot, error) {
 	content, err := os.ReadFile(path)
 	if err != nil {
@@ -341,6 +384,8 @@ func readGatewaySnapshot(path string, port int) (hostnginx.Snapshot, error) {
 	return hostnginx.Snapshot{Content: content, ActivePort: port}, nil
 }
 
+// verifyFileIdentity 校验文件的实际尺寸与 SHA-256 摘要是否与给定身份一致，任何
+// 不一致都返回错误。
 func verifyFileIdentity(path string, identity filestore.Identity) error {
 	if err := identity.Validate(); err != nil {
 		return err
@@ -361,11 +406,14 @@ func verifyFileIdentity(path string, identity filestore.Identity) error {
 	return nil
 }
 
+// snapshotDigest 计算 Nginx 快照内容的 SHA-256 摘要（十六进制字符串），用于
+// 回执与意图中的一致性标识。
 func snapshotDigest(snapshot hostnginx.Snapshot) string {
 	digest := sha256.Sum256(snapshot.Content)
 	return hex.EncodeToString(digest[:])
 }
 
+// gatewayResult 将 Nginx 快照的活动端口与内容摘要序列化为事务检查结果的 JSON。
 func gatewayResult(snapshot hostnginx.Snapshot) json.RawMessage {
 	result, _ := json.Marshal(struct {
 		ActivePort int    `json:"activePort"`
@@ -374,6 +422,7 @@ func gatewayResult(snapshot hostnginx.Snapshot) json.RawMessage {
 	return result
 }
 
+// pathResult 将路径及其状态序列化为事务检查结果的 JSON。
 func pathResult(path string, state pathState) json.RawMessage {
 	result, _ := json.Marshal(struct {
 		Path  string    `json:"path"`
@@ -382,6 +431,7 @@ func pathResult(path string, state pathState) json.RawMessage {
 	return result
 }
 
+// syncDirectory 打开目录并执行 fsync，将目录项变更持久化到磁盘。
 func syncDirectory(directory string) error {
 	file, err := os.Open(directory)
 	if err != nil {