systemd StateDirectory 怎样保存服务状态文件

服务需要保存游标、索引、去重标记或上次处理位置时，最容易出现的问题不是“目录不存在”，而是目录由谁创建、服务用户能否写入、升级后路径是否一致。StateDirectory= 就是 systemd 为这类持久状态提供的 unit 声明：目录放在系统状态树下，服务启动时由 systemd 准备好，并通过 $STATE_DIRECTORY 把实际路径交给进程。

官方地址：https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html

先建立状态目录的基线

先把服务的文件分成三类：重启后仍要保留的状态放入 state，进程运行期间才需要的 PID、socket 或临时文件放入 runtime，日志则交给日志目录或日志系统。本文只处理第一类。这样做的好处是，状态文件的生命周期、权限和容量都能单独观察，不会与一次启动产生的临时文件混在一起。

在改 unit 前可以记录当前目录情况。下面的命令只是读取本机目录信息，不代表本文已经在某台服务器上执行；生产环境应替换服务名和实际路径。

# 读取状态目录的所有者、权限和占用，先建立变更前基线
sudo stat -c '%A %U:%G %n' /var/lib/state-demo
sudo du -sh /var/lib/state-demo
sudo find /var/lib/state-demo -maxdepth 1 -type f | wc -l

如果目录还不存在，stat 返回失败是正常现象，它说明当前 unit 还没有声明或准备这条状态边界。不要为了让命令通过而先用 root 手工创建一个目录；否则后续很难判断目录权限究竟来自 unit 还是来自历史操作。

在 unit 中声明 StateDirectory

把目录名写进服务的 [Service] 段。下面的示例故意使用专用服务用户，并把目录权限写成一个可审查的起点：

[Unit]
Description=State directory demo service
After=network.target

[Service]
Type=simple
User=state-demo
Group=state-demo
ExecStart=/usr/local/bin/state-demo
# 让 systemd 管理 /var/lib/state-demo 这类持久目录
StateDirectory=state-demo
# 目录权限先收窄到服务用户和同组进程，再按实际协作需求调整
StateDirectoryMode=0750
Restart=on-failure

[Install]
WantedBy=multi-user.target

这里的关键不是把 /var/lib/state-demo 写进 ExecStart，而是声明目录的语义名称。systemd 会根据 StateDirectory= 在状态目录树下准备目录，并让服务进程获得对应的环境变量。服务用户需要能够访问目录；如果程序还要创建子目录或改写文件，目录模式、文件所有者和程序自身的 umask 也要一起考虑。

让程序使用 STATE_DIRECTORY

目录由 unit 决定后，程序只需要读取环境变量并拼接自己的文件名。这样同一份二进制可以在常规主机、不同根目录或打包环境中复用，不必把发行版的目录布局复制到业务代码里。

package main

import (
    "fmt"
    "os"
    "path/filepath"
)

func stateFile() (string, error) {
    // systemd 为使用 StateDirectory 的服务提供状态目录路径。
    dir := os.Getenv("STATE_DIRECTORY")
    if dir == "" {
        return "", fmt.Errorf("STATE_DIRECTORY 未设置")
    }

    // 只拼接固定文件名，避免把用户输入直接当成路径片段。
    return filepath.Join(dir, "checkpoint.json"), nil
}

func main() {
    path, err := stateFile()
    if err != nil {
        // 非 systemd 环境明确失败，避免静默写到当前工作目录。
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
    fmt.Println(path)
}

需要注意的是，STATE_DIRECTORY 是运行环境提供的接口，不应在 unit 里手工写成固定值来“模拟”它。开发环境如果要脱离 systemd 启动，可以在测试命令中显式提供一个临时目录，但这属于测试配置，不要把这个兜底路径带进生产服务。

把写权限限制在状态边界

如果服务只需要写自己的状态，建议同时考虑系统目录保护。ProtectSystem=strict 可以把系统文件系统的大部分写入面收紧；StateDirectory= 则明确告诉 systemd 哪个状态目录是服务的写入边界。两者的组合比“给服务整个 /var/lib 写权限”更容易审查。

[Service]
User=state-demo
Group=state-demo
StateDirectory=state-demo
StateDirectoryMode=0750
# 默认把系统目录视为只读，只保留声明的状态写入面
ProtectSystem=strict
# 禁止服务获得不需要的其他能力，具体权限按程序依赖增量开放
NoNewPrivileges=yes

不要把 ProtectSystem=strict 当成自动修复权限的开关。程序如果需要写配置、上传目录或其他路径，应先重新划分数据职责，再通过相应的 systemd 目录选项或明确的绑定路径授权。一个 unit 能写很多目录，往往说明状态边界还没有定义清楚。

用指标确认 StateDirectory 是否真的解决了问题

配置完成后，验证重点是“声明、权限、容量、持久性”四项，而不是只看服务是否能启动。可以把下面四类指标记成部署前后的对照表：

# 读取 unit 对 StateDirectory 的声明，不修改 unit
systemctl show state-demo.service --property=StateDirectory

# 查看服务用户与目录权限，确认写入边界没有扩大
systemctl show state-demo.service --property=User --property=Group
sudo stat -c '%A %U:%G %n' /var/lib/state-demo

# 重新采集容量和文件数量，作为部署后的简单增长指标
sudo du -sh /var/lib/state-demo
sudo find /var/lib/state-demo -maxdepth 1 -type f | wc -l

如果服务重启后状态文件消失，先确认使用的是 StateDirectory= 而不是 RuntimeDirectory=，再确认清理脚本、tmpfiles 规则或部署流程没有主动删除它。若服务能启动但无法写入，优先对照 User=、Group=、目录模式和程序的实际写入文件名，而不是直接把目录改成 0777。

几个容易混淆的边界

StateDirectory 和 RuntimeDirectory 不一样。前者面向跨重启保留的服务状态，后者面向运行期间的临时对象。socket、PID 文件和短生命周期锁文件通常不应该混进 state 目录。

StateDirectory 不是备份策略。systemd 负责目录的声明式准备和权限衔接，不会替你设计跨主机备份、版本迁移、损坏恢复和容量上限。需要可靠恢复时，仍应把状态文件纳入备份与升级方案。

目录存在不代表业务写入正确。文件名、原子替换、fsync、并发写入和损坏恢复仍然是程序责任。StateDirectory 解决的是目录边界，不是状态文件格式本身。

常见问题

StateDirectory 会在服务停止时删除状态文件吗？

它用于持久状态，不能按运行时目录的语义理解。是否删除还要看 unit 之外的清理脚本、tmpfiles 规则和部署逻辑；需要长期保留的内容不要交给外部清理任务后又假设 systemd 会备份。

可以同时声明多个 StateDirectory 吗？

可以按 systemd 支持的空白分隔形式声明多个目录名，但更重要的是先判断它们是否真的代表不同的生命周期或权限边界。目录只是为了“看起来整齐”而拆分，反而会让备份和监控更分散。

为什么程序里不应该直接写死 /var/lib/state-demo？

直接路径会把部署布局耦合进二进制，也绕开 unit 对目录的声明。读取 STATE_DIRECTORY 能让 unit 成为配置来源，程序只关心状态文件相对目录的位置。

StateDirectoryMode=0750 是否适合所有服务？

不一定。它只是一个收窄权限的起点；如果同组进程需要读取、服务需要多用户协作或状态文件包含敏感内容，应结合实际用户模型、umask 和备份权限重新确定。

总结

把服务状态交给 systemd 管理，核心是三件事：用 StateDirectory= 声明持久目录，用 $STATE_DIRECTORY 让程序脱离固定路径，再用用户、目录模式和系统目录保护把写入面收窄。部署时围绕声明、权限、容量和持久性建立基线，就能把“服务能启动”进一步落实成“状态边界可解释、可观察、可恢复”。