把 Ansible 巡检放进 Semaphore

只有两台服务器时，逐台登录查看磁盘还能应付。机器多了以后，很容易漏一台，或者忘记自己上次查过什么。Semaphore UI 可以给 Ansible 任务一个网页入口，保留执行结果和时间。

先把它用于读取状态的巡检，再考虑配置变更。本文采用 PostgreSQL，避免不同 SQLite 部署版本的数据路径差异；不给容器 Docker socket，也不默认分发 root 密钥。

配置数据库和任务凭据密钥

Semaphore 要保存项目配置与凭据，还要能连接目标主机。准备另购 VPS 时，可以从雨云云服务器查看服务器配置，并确认它到被巡检主机的 SSH 网络是否可用。优惠码 KuZhuJi。如有消费返利，以购买页所选规格显示的金额为准。

以下命令在 Linux VPS 上执行，需要有 Docker 操作权限。先运行 docker version 和 docker compose version，确认引擎与 Compose v2 都能工作。没有安装 Docker 时，按 Docker 官方安装说明选择对应发行版；不要把其他发行版的仓库配置直接复制过来。

示例工作目录为 /opt/semaphore，所有相对路径都以这个目录为基准。VPS_IP、SSH 用户和示例域名需要换成自己的值。端口 3004 若已被占用，只改映射左侧的宿主机端口，并同步修改访问地址。

sudo install -d -m 0750 -o "$(id -u)" -g "$(id -g)" /opt/semaphore
cd /opt/semaphore
umask 077

新建 .env，数据库与管理员分别使用随机密码，加密密钥使用 openssl rand -base64 32：

DB_PASSWORD=REPLACE_WITH_RANDOM_DB_PASSWORD
ADMIN_EMAIL=you@example.com
ADMIN_PASSWORD=REPLACE_WITH_RANDOM_ADMIN_PASSWORD
ENCRYPTION_KEY=REPLACE_WITH_BASE64_KEY

mkdir -p database
chmod 600 .env

ENCRYPTION_KEY 用来保护保存的访问凭据，不能在每次重建容器时重新生成。已有安装的管理员密码也不要假定改环境变量就一定能重置。

将下面内容保存为 compose.yaml：

services:
  db:
    image: postgres:17
    restart: unless-stopped
    environment:
      POSTGRES_USER: semaphore
      POSTGRES_DB: semaphore
      POSTGRES_PASSWORD: ${DB_PASSWORD:?set db password}
    volumes:
      - ./database:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U semaphore -d semaphore"]
      interval: 10s
      timeout: 5s
      retries: 10
  semaphore:
    image: semaphoreui/semaphore:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:3004:3000"
    environment:
      SEMAPHORE_DB_DIALECT: postgres
      SEMAPHORE_DB_HOST: db
      SEMAPHORE_DB_PORT: 5432
      SEMAPHORE_DB: semaphore
      SEMAPHORE_DB_USER: semaphore
      SEMAPHORE_DB_PASS: ${DB_PASSWORD}
      SEMAPHORE_PLAYBOOK_PATH: /tmp/semaphore
      SEMAPHORE_ADMIN: admin
      SEMAPHORE_ADMIN_NAME: Administrator
      SEMAPHORE_ADMIN_EMAIL: ${ADMIN_EMAIL:?set email}
      SEMAPHORE_ADMIN_PASSWORD: ${ADMIN_PASSWORD:?set admin password}
      SEMAPHORE_ACCESS_KEY_ENCRYPTION: ${ENCRYPTION_KEY:?set encryption key}
    depends_on:
      db:
        condition: service_healthy

在工作目录启动并检查日志：

docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=80

启动后按下面的步骤试用。遇到目录不可写的报错，先核对 UID 和挂载路径，不要直接改成 chmod 777。

用 SSH 隧道打开界面

示例仅把应用端口发布到 VPS 的 127.0.0.1。在自己的电脑上运行以下命令，保留终端窗口，再打开 http://127.0.0.1:3004：

ssh -N -L 3004:127.0.0.1:3004 your_ssh_user@VPS_IP

浏览器里的回环地址是自己的电脑，SSH 把请求转到 VPS。若本地同号端口被占用，可换隧道左侧端口；涉及应用外部 URL 的项目也要一起调整。管理界面无需因此开放公网端口。

先做一次只读巡检

准备一个自己维护的 Git 仓库，放入下面的 playbook：

- name: Read server status
  hosts: all
  gather_facts: false
  tasks:
    - name: Check connectivity
      ansible.builtin.ping:
    - name: Read disk usage
      ansible.builtin.command: df -h
      changed_when: false

在 Semaphore 中建立项目、仓库、凭据和 inventory，再创建任务模板指向这个文件。inventory 先只包含一台测试服务器，使用专用普通 SSH 账号。首次建立连接前核对主机指纹，不通过关闭主机检查来省事。

执行后应看到 ping 成功、磁盘结果和未发生变更的状态。若目标机器缺少 Python，先处理 Ansible 运行条件；任务执行器容器的网络也必须能访问目标 SSH 地址。

确认无误后再逐步扩展机器列表。安装软件、重启服务等变更任务单独建立模板，限制谁能运行，并先在测试机检查，不与巡检按钮混用。

备份任务数据与原加密密钥

备份 PostgreSQL 数据和原加密密钥；playbook 由 Git 仓库另行保留。恢复后先检查任务模板和凭据，再运行测试机巡检，不能对整批生产机器直接验证。

在工作目录执行下面的停机备份，压缩包保存在应用目录之外。停止全部服务会带来短暂不可用；确认停止成功后再打包。

docker compose stop
sudo install -d -m 0700 /var/backups/docker-apps
backup_file="/var/backups/docker-apps/$(basename "$PWD")-$(date +%Y%m%d-%H%M%S).tar.gz"
sudo tar -czpf "$backup_file" compose.yaml database .env
sudo chmod 0600 "$backup_file"
sudo tar -tzf "$backup_file" | head
docker compose start

将压缩包复制到 VPS 之外。恢复时，在另一台测试机器的空目录解包，保留文件所有者和相对路径，用原镜像版本启动，检查前面提到的数据。不要直接覆盖正在使用的原数据目录。

升级前先记录镜像 ID 或摘要，并保存这份备份。阅读项目更新说明后再拉取镜像；涉及数据库迁移时，回滚需要恢复旧数据与旧镜像，不能只把标签改回去。

安装参数和数据路径可对照Semaphore UI Docker 文档。