refactor: use nginx -s reload instead of systemd

- doc: add comment

main.go

@@ -1,3 +1,5 @@
+// 本包是 yms-daemon 的入口，根据可执行文件名决定运行角色：
+// 当二进制名为 ymsd 时作为守护进程服务端长期运行，否则作为 ymsctl 命令行客户端处理用户命令。
 package main
 
 import (
@@ -29,8 +31,12 @@ import (
 	"yms-daemon/internal/transaction"
 )
 
+// serviceBackend 当前命令行客户端与守护进程唯一支持的目标服务名。
 const serviceBackend = "backend"
 
+// main 进程入口，负责根据可执行文件名分流到守护进程服务端或命令行客户端。
+// 它先建立可被 os.Interrupt 与 SIGTERM 中断的上下文，再判断二进制名是否为 ymsd：
+// 是则校验不接受任何参数并运行 runServe，否则把剩余参数交给 run 处理并以返回码退出。
 func main() {
 	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
 	defer cancel()
@@ -48,6 +54,10 @@ func main() {
 	os.Exit(run(ctx, os.Args[1:], os.Stdout, os.Stderr))
 }
 
+// run 解析并执行命令行客户端的一个子命令，返回进程退出码。
+// arguments 去除程序名后的命令行参数，stdout 与 stderr 分别接收正常输出与错误输出。
+// 它支持 update、list、restart、help 子命令；无参数或未知命令时向 stderr 输出用法并返回 2，
+// 命令执行失败返回 1，成功返回 0。
 func run(ctx context.Context, arguments []string, stdout io.Writer, stderr io.Writer) int {
 	if len(arguments) == 0 {
 		writeUsage(stderr)
@@ -125,20 +135,34 @@ func run(ctx context.Context, arguments []string, stdout io.Writer, stderr io.Wr
 	}
 }
 
+// updateArguments 保存 update 子命令解析后的参数。
 type updateArguments struct {
-	service        string
-	inputType      string
-	file           string
-	imageReference string
-	quite          bool
-	startLog       bool
-}
-
-type restartArguments struct {
+	// service 目标服务名，当前仅接受 backend。
 	service string
-	quite   bool
+	// inputType 更新输入类型，由 -f 或 --native-jar 推导得到。
+	inputType string
+	// file 本地制品的绝对路径，容器镜像输入时为空。
+	file string
+	// imageReference 容器镜像引用，仅在 --container-image 输入时非空。
+	imageReference string
+	// quite 为真时抑制进度与成功结果的输出。
+	quite bool
+	// startLog 为真时在容器更新完成后输出启动日志。
+	startLog bool
 }
 
+// restartArguments 保存 restart 子命令解析后的参数。
+type restartArguments struct {
+	// service 目标服务名，当前仅接受 backend。
+	service string
+	// quite 为真时抑制进度与成功结果的输出。
+	quite bool
+}
+
+// parseUpdateArgs 解析 update 子命令的 flag 参数并做业务校验。
+// 它要求 --service 必须为 backend，-f、--native-jar、--container-image 三者必须且只能提供一个；
+// 对文件类输入会解析为绝对路径并校验其为非符号链接的普通文件，容器镜像输入不允许附带 --no-start-log。
+// 校验失败时向 output 写入原因并返回 error。
 func parseUpdateArgs(arguments []string, output io.Writer) (updateArguments, error) {
 	flags := flag.NewFlagSet("update", flag.ContinueOnError)
 	flags.SetOutput(output)
@@ -192,6 +216,8 @@ func parseUpdateArgs(arguments []string, output io.Writer) (updateArguments, err
 	return updateArguments{service: *service, inputType: inputType, file: absoluteFile, quite: *quite}, nil
 }
 
+// parseRestartArgs 解析 restart 子命令的 flag 参数并做业务校验。
+// 它要求 --service 必须为 backend，且不接受任何位置参数；校验失败时向 output 写入原因并返回 error。
 func parseRestartArgs(arguments []string, output io.Writer) (restartArguments, error) {
 	flags := flag.NewFlagSet("restart", flag.ContinueOnError)
 	flags.SetOutput(output)
@@ -209,6 +235,9 @@ func parseRestartArgs(arguments []string, output io.Writer) (restartArguments, e
 	return restartArguments{service: *service, quite: *quite}, nil
 }
 
+// runServe 以守护进程服务端角色运行：初始化日志、获取进程锁、加载部署配置、
+// 打开事务存储与协调器、构建 Nginx 控制器与后端更新器，最后通过 daemonserver 开始服务。
+// 它使用具名返回 result 以便在各资源清理阶段合并所有 Close 错误，最终返回服务端的运行错误。
 func runServe(ctx context.Context) (result error) {
 	logger, logCloser, err := logging.New(runtimepaths.Log)
 	if err != nil {
@@ -238,8 +267,6 @@ func runServe(ctx context.Context) (result error) {
 	gateway, err := hostnginx.NewController(
 		runtimepaths.HostNginxConfig,
 		runtimepaths.HostNginxExecutable,
-		config.Backend.SystemctlPath,
-		runtimepaths.HostNginxService,
 	)
 	if err != nil {
 		return err
@@ -277,6 +304,7 @@ func runServe(ctx context.Context) (result error) {
 	return server.Serve(ctx)
 }
 
+// writeUsage 向 output 写出命令行客户端各子命令的用法说明。
 func writeUsage(output io.Writer) {
 	fmt.Fprintln(output, "usage:")
 	fmt.Fprintln(output, "  ymsctl update --service backend -f <repack.zip> [--quite]")
@@ -286,6 +314,8 @@ func writeUsage(output io.Writer) {
 	fmt.Fprintln(output, "  ymsctl list [--limit <n>] [--service backend] [--state <state>] [--json]")
 }
 
+// writeUpdateProgress 把一条进度事件格式化写入 output：状态字段左对齐占 14 列，
+// 状态为空时显示为 INFO，随后输出事件消息。
 func writeUpdateProgress(output io.Writer, event daemonapi.Response) {
 	state := event.State
 	if state == "" {
@@ -294,6 +324,9 @@ func writeUpdateProgress(output io.Writer, event daemonapi.Response) {
 	fmt.Fprintf(output, "%-14s %s\n", state, event.Message)
 }
 
+// runList 执行 list 子命令：解析过滤参数，打开事务存储读取最近事务，
+// 按是否指定 --json 决定以稳定 JSON 或制表符分隔的表格形式输出到 stdout。
+// 它支持 --limit、--service、--state、--json 四个选项，返回查询或输出阶段的错误。
 func runList(ctx context.Context, arguments []string, stdout, stderr io.Writer) error {
 	flags := flag.NewFlagSet("list", flag.ContinueOnError)
 	flags.SetOutput(stderr)