Debian 定时器如何文档化

Debian 定时器文档化实践

一 文档化目标与产出

• 明确每个定时器的业务目的、触发规则、运行身份、日志与监控方式，确保运维、开发、审计均可快速理解并安全变更。
• 建议沉淀为两类文档：
  • 面向团队的“定时器目录/索引页”（按业务域分组，列出关键元数据与变更记录）。
  • 贴近单元的“README/手册页”（嵌入或外链到单元文件，说明配置语义与注意事项）。

二 推荐的元数据字段与模板

• 建议将以下字段写入单元文件的 Description 或同目录的 README.md，并统一格式（YAML 片段或 INI 注释），便于机器解析与人工阅读。

• 示例（将关键元数据写入单元文件头部注释，便于“systemctl cat”直接查看）：

# Name:          backup-db.timer
# Purpose:       Daily PostgreSQL full backup at 02:00 (CST)
# Owner:         alice@example.com
# Schedule:      OnCalendar=*-*-* 02:00:00; TZ=Asia/Shanghai
# RunAs:         User=backup; Group=backup
# Logs:          journalctl -u backup-db.timer -u backup-db.service
# Metrics:       up{job="backup-db"}; alert if failure > 1%/day
# Concurrency:   RandomizedDelaySec=5m
# Artifacts:     /var/backups/db-*.sql.gz (7d)
# ChangeLog:
#   2025-09-01: Shift schedule to 02:00 to avoid peak load

三 在 systemd 单元中记录关键信息

• 在 .timer 与 .service 的 Description 中放入“用途 + 负责人 + 关键时间/时区”，在 [Timer] 中明确 OnCalendar、Persistent、AccuracySec、RandomizedDelaySec 等语义清晰的配置，并显式声明 Unit= 指向的服务，避免歧义。
• 示例模板（含文档化注释与可观测性挂钩）：

# /etc/systemd/system/backup-db.timer
[Unit]
Description=Daily PostgreSQL backup at 02:00 (CST) | Owner: alice@example.com
Documentation=https://git.example.com/ops/backup-db

[Timer]
OnCalendar=*-*-* 02:00:00
Persistent=true
AccuracySec=1s
RandomizedDelaySec=5m
Unit=backup-db.service

[Install]
WantedBy=timers.target

# /etc/systemd/system/backup-db.service
[Unit]
Description=Run PostgreSQL backup | Owner: alice@example.com
After=postgresql.service network-online.target
Requires=network-online.target

[Service]
Type=oneshot
User=backup
Group=backup
ExecStart=/usr/local/bin/backup-db.sh
ExecStartPre=/usr/local/bin/backup-db-prepare.sh
ExecStartPost=/usr/local/bin/backup-db-verify.sh
StandardOutput=journal
StandardError=journal
SuccessExitStatus=0 1   # 1 表示“备份已存在/无需重复”，不视为失败
Restart=on-failure
RestartSec=30

# 可选：对接监控/告警
# Environment=NOTIFY_SOCKET=/run/systemd/notify

• 说明：
  • Persistent=true 可在系统错过触发后于下次启动补执行，适合关键日常任务。
  • AccuracySec 与 RandomizedDelaySec 有助于错峰与降低“惊群”。

四 变更与验证流程

• 变更前：在“定时器目录/索引页”新增或更新条目，填写上述元数据，关联变更单与回滚方案。
• 变更中：
  • 新增/修改单元后执行 systemctl daemon-reload，再启用/重启定时器：
    • 启用并立即启动：systemctl enable --now backup-db.timer
    • 仅启动：systemctl start backup-db.timer
  • 校验调度是否正确：
    • 查看下次触发时间：systemctl list-timers --all | grep backup-db
    • 查看单元状态与日志：systemctl status backup-db.timer backup-db.service；journalctl -u backup-db.service -b
• 变更后：在“ChangeLog”记录时间与原因，并同步更新监控/告警阈值说明。

五 可视化与审计建议

• 统一目录：将所有自定义定时器集中到 /etc/systemd/system/，按业务命名（如 backup-*.timer、cleanup-*.timer），并在 README.md 中维护索引表（字段见第二部分）。
• 可观测性：
  • 统一用 journald 输出，约定日志级别与结构化字段（如 task=backup-db, outcome=success|fail）。
  • 暴露 systemd unit 健康指标（如用 node_exporter textfile 收集 “up{job=“backup-db”}=1/0”），并在告警中引用。
• 审计与合规：
  • 将定时器定义纳入 Git 管理，禁止在生产环境直接编辑；通过 .deb 包或 Ansible 角色分发，变更留痕。
  • 定期巡检：systemctl list-timers --all 与索引页对账，清理已废弃定时器。