systemd-state HTTP服务器 Docker镜像文档

镜像概述和主要用途

systemd-state 是一个小型HTTP服务器，用于暴露systemd的整体运行状态，功能等效于执行 systemctl is-system-running 命令。其核心用途是作为轻量级监控解决方案，将系统状态以HTTP接口形式提供给外部监控服务（如Pingdom、StatusCake等），便于快速判断系统是否正常运行。

核心功能和特性

系统状态与HTTP状态码映射

服务器通过HTTP状态码反馈systemd系统状态，具体对应关系如下：

• 200 OK：系统完全正常运行（对应 systemctl is-system-running 返回 running）。
• 503 Internal Server Error：系统处于非正常状态（如 degraded、maintenance、starting、stopping 等）。
• 500 Service Unavailable：无法获取systemd状态（如权限不足或系统不支持systemd）。

轻量级设计

程序体积小，资源占用低，仅依赖systemd的运行时信息，无需复杂配置。

使用场景和适用范围

适用场景

• 需通过外部监控服务（如Pingdom、StatusCake）监测服务器系统状态的场景。
• 缺乏复杂监控系统（如Prometheus）时，作为"简易版"系统健康检查工具。

限制说明

• 仅适用于运行systemd的Linux系统。
• 不提供HTTPS加密或身份认证，需结合反向代理实现安全访问。

详细使用方法和配置说明

镜像获取

Docker Hub地址：arnested/systemd-state
拉取命令：

docker pull arnested/systemd-state

基本运行方式（docker run）

需挂载主机的 /run/systemd/ 目录（只读）以获取systemd状态：

docker run -d \
  --name systemd-state \
  -v /run/systemd/:/run/systemd/:ro \
  -p 8080:80 \
  --restart always \
  arnested/systemd-state

• -v /run/systemd/:/run/systemd/:ro：挂载systemd运行时目录（只读权限，确保安全性）。
• -p 8080:80：将容器内80端口映射到主机8080端口（可根据需求调整）。
• --restart always：确保容器异常退出后自动重启。

访问 http://<主机IP>:8080 即可获取系统状态（通过HTTP状态码判断）。

Docker Compose配置示例（结合Traefik反向代理）

以下示例通过Traefik暴露HTTPS接口并添加基本认证，适用于生产环境。

配置说明

• 暴露路径：[***]。
• 基本认证：用户 foo，密码 bar（示例密码哈希需替换为实际生成值）。
• 网络：使用Traefik的外部网络 traefik_webgateway。

docker-compose.yml

version: "2"

services:
  systemd-state:
    image: arnested/systemd-state
    volumes:
      - '/run/systemd/:/run/systemd/:ro'  # 只读挂载systemd运行时目录
    restart: always
    labels:
      - 'traefik.frontend.auth.basic=foo:$$apr1$$WCYo2XY2$$7PDdo922necZuGkMAeTI70'  # 基本认证（示例哈希对应密码bar）
      - "traefik.port=80"  # 容器内服务端口
      - "traefik.enable=true"  # 启用Traefik代理
      - "traefik.frontend.rule=Host:example.com;Path:/_systemd"  # 路由规则（替换为实际域名）
    networks:
      - web

networks:
  web:
    external:
      name: traefik_webgateway  # 关联Traefik外部网络

生成基本认证哈希

使用 htpasswd 生成密码哈希（需安装apache2-utils）：

htpasswd -n foo
# 输入密码后输出类似：foo:$apr1$WCYo2XY2$7PDdo922necZuGkMAeTI70

将生成的哈希替换到 traefik.frontend.auth.basic 标签中。

安全性说明

• 无HTTPS和认证：默认仅通过HTTP暴露，无身份认证。建议通过反向代理（如Traefik、Nginx）添加HTTPS加密和认证（如基本认证、OAuth2）。
• 权限控制：挂载 /run/systemd/ 时使用只读权限（:ro），避免容器修改主机系统状态。

常见问题

为何不支持TLS或认证？

设计理念与Prometheus类似，优先保证简单性和轻量性。如需安全访问，建议通过反向代理层实现（如Traefik、Nginx）。详情可参考Prometheus FAQ。

如何判断服务是否正常运行？

访问HTTP接口后，通过状态码判断：200表示系统正常，503表示系统异常，500表示无法获取状态（需检查容器是否正确挂载 /run/systemd/ 目录）。