Docker Compose是官方唯一推荐的Semaphore部署方式，因其不提供系统级安装包，yum/apt安装会误装同名终端工具；必须预装Ansible CLI并配置MySQL/PostgreSQL数据库连接参数，避免SQLite并发锁死，且Nginx反代需透传Upgrade和Connection头以保障WebSocket正常。
直接用 Docker Compose 跑 Semaphore，别碰源码编译或裸装依赖。它本身不提供系统级安装包，官方唯一推荐路径就是容器化部署，否则极易因 SQLite 并发、MySQL 驱动缺失、Go 版本不匹配等问题卡在 semaphore 启动阶段。
为什么不能用 yum/apt 直接装 Semaphore
Semaphore 不是传统 Linux 软件包，没有 semaphore 的 deb/rpm 包。所有“yum install semaphore”或“apt install semaphore”的教程都是错的——它们实际装的是另一个叫 semaphore 的终端复用工具（类似 tmux），和 Ansible Web UI 完全无关。你执行 semaphore --version 报错或输出 “Semaphore terminal multiplexer” 就是掉进这个坑了。
必须先装好 Ansible，但别 pip install ansible
Semaphore 本身不运行 Ansible，但它调用本地 ansible 和 ansible-playbook 命令。所以控制机上必须已存在可用的 Ansible CLI：
- Ubuntu/Debian：用
sudo apt install ansible（别加 PPA，新版 PPA 会装错ansible-core而缺集合） - RHEL/CentOS 8+：先
sudo dnf install epel-release，再sudo dnf install ansible（注意不是ansible-core） - CentOS 7：
sudo yum install epel-release && sudo yum install ansible - 装完立刻验证：
ansible --version输出里configured module search path不能是空列表，否则后续跑 playbook 必报MODULE FAILURE
docker-compose.yml 里这几个环境变量不能少
官方 semaphoreui/semaphore:latest 镜像默认用 SQLite，只适合单人临时试用。生产环境必须连 MySQL 或 PostgreSQL，否则多用户并发任务会锁死：
-
SEMAPHORE_DB_DIALECT必须设为mysql或postgres，不能留空或写sqlite -
SEMAPHORE_DB_HOST指向真实数据库容器名（如db），不是localhost（Docker 内部网络不认这个） -
SEMAPHORE_DB_PORT对 MySQL 是3306，PostgreSQL 是5432，别抄错 - MySQL 容器必须提前建库并授权：
CREATE DATABASE semaphore CHARACTER SET utf8mb4;+GRANT ALL ON semaphore.* TO 'semaphore'@'%';
启动后登录失败？检查 /etc/semaphore/config.json 是否被覆盖
Docker 方式启动时，如果挂载了 volumes: - ./semaphore:/etc/semaphore，但宿主机 ./semaphore 目录为空或含旧配置，Semaphore 会因读不到 config.json 而拒绝初始化，Web 页面一直转圈或返回 500。正确做法是：
- 首次启动前不要挂载该目录，让容器自动生成默认
config.json - 等服务起来、能登录后，再
docker cp semaphore:/etc/semaphore/config.json ./semaphore/导出修改 - 改完再挂载，否则每次
docker-compose up -d都会覆盖你的改动
最常被忽略的一点：Semaphore 的 Web 界面监听在容器内 :3000，但它的 API 和 WebSocket 也依赖同一端口。如果你用 Nginx 反代，必须透传 Upgrade 和 Connection 头，否则任务日志实时输出会断连——这不是 Ansible 问题，是反向代理没配对。
