afsharidevops/awx

AWX 23.9.0 - 本地Docker Compose部署（afsharidevops/awx:23.9.0）

⚠️ 仅用于本地开发/演示（生产环境请使用AWX Operator）

镜像概述和主要用途

本镜像基于AWX 23.9.0版本，镜像使用流程与上游tools/docker-compose保持一致，固定了自定义镜像版本，并修复了常见的collectstatic/uWSGI崩溃循环问题（导致502/404错误）。同时包含关键AWX初始化命令（clean-ui、ui-devel、createsuperuser、create_preload_data），方便快速搭建本地开发或演示环境。

核心功能和特性

• 基于AWX 23.9.0稳定版本，与上游源码同步
• 修复collectstatic执行失败导致的uWSGI崩溃问题，解决502/404错误
• 内置UI资产重建、超级用户创建、默认数据预加载等初始化命令
• 提供完整的Docker Compose部署配置，包含Nginx、PostgreSQL、Redis等依赖服务
• 支持数据持久化卷挂载，确保开发环境数据不丢失

使用场景和适用范围

• 适用场景：本地开发环境、功能演示、学习测试
• 环境要求：
  • Linux主机，已安装Docker和Docker Compose插件（需支持docker compose version命令）
  • 推荐配置：4+ vCPU、6+ GB RAM
  • 主机需开放端口：8043（HTTPS UI访问）
• 不适用场景：生产环境（生产环境请使用AWX Operator）

使用方法和配置说明

1. 准备环境

确保已安装Docker和Docker Compose插件：

bash
docker --version
docker compose version

2. 拉取AWX 23.9.0源码

bash
mkdir -p /opt/awx && cd /opt/awx
git clone https://github.com/ansible/awx.git
cd awx
git checkout 23.9.0
cd tools/docker-compose/_sources
pwd   # 确认路径：/opt/awx/awx/tools/docker-compose/_sources
ls -1  # 应显示：docker-compose.yml、nginx.conf、nginx.locations.conf、SECRET_KEY、websocket_secret.py、database.py等文件

若SECRET_KEY或websocket_secret.py文件缺失，需手动创建（本地开发可填写任意非空随机字符串）。

3. 固定自定义镜像版本

修改docker-compose.yml文件，将AWX镜像指定为afsharidevops/awx:23.9.0：

bash
sed -i 's|\(image:\s*\).*awx:.*|\1afsharidevops/awx:23.9.0|' docker-compose.yml

（可选）添加默认管理员 credentials（若配置中不存在）：

bash
awk '
  BEGIN{p=1}
  /services:/ {print; next}
  /awx:/ && p {print; getline; print "    environment:"; print "      AWX_ADMIN_USER: admin"; print "      AWX_ADMIN_PASSWORD: changeme"; p=0}
  {print}
' docker-compose.yml > docker-compose.yml.new && mv docker-compose.yml.new docker-compose.yml

4. 启动服务栈

bash
docker compose pull  # 拉取镜像
docker compose up -d  # 后台启动服务
docker compose logs -f awx  # 查看awx容器日志，确认启动状态

5. 初始化AWX和UI

待容器（tools_awx_1）运行后，执行以下初始化命令：

重建AWX UI资产（确保前端正常加载）

bash
docker exec tools_awx_1 make clean-ui ui-devel

创建管理员超级用户（交互式）

bash
docker exec -ti tools_awx_1 awx-manage createsuperuser

预加载默认组织、项目和 inventory

bash
docker exec tools_awx_1 awx-manage create_preload_data

6. 访问UI

打开浏览器访问 https://<主机IP>:8043（接受自签名证书）。
使用创建的超级用户凭据登录。若已配置环境变量，默认凭据为：admin / changeme。

健康检查命令：

bash
# 本地访问检查
curl -k https://localhost:8043/api/v2/ping/
# 容器内服务检查
docker compose exec awx bash -lc 'curl -sS -i http://127.0.0.1:8050/api/v2/ping/ || true'

7. 数据持久化卷

以下卷用于持久化数据：

• PostgreSQL数据：pgdata
• Redis数据：redisdata
• 项目文件：awx_projects → 映射至容器内/var/lib/awx/projects
• AWX数据：awx_data → 映射至容器内/var/lib/awx
• 静态资源：awx_static → 映射至容器内/var/lib/awx/public/static

备份示例（以pgdata为例）：

bash
docker compose stop awx  # 停止awx服务
# 备份pgdata卷数据至当前目录
docker run --rm -v pgdata:/from -v "$(pwd)":/to alpine sh -c 'cd /from && tar czf /to/pgdata.tgz .'
docker compose start awx  # 启动awx服务

8. 日常运维

bash
# 查看服务状态
docker compose ps
# 实时查看awx日志
docker compose logs -f awx
# 重启awx服务
docker compose restart awx

升级镜像（未来版本）：

bash
# 修改镜像标签为新版本
sed -i 's|afsharidevops/awx:23.9.0|afsharidevops/awx:<新版本标签>|' docker-compose.yml
# 拉取新镜像并重启服务
docker compose pull awx && docker compose up -d

9. 故障排除 - 502/404错误（uWSGI/collectstatic循环）

症状

• 浏览器显示502 Bad Gateway或404 Not Found
• supervisorctl status显示：tower-processes:awx-uwsgi FATAL
• /var/log/nginx/error.log日志包含：no live upstreams或connect() failed (111)

根本原因

supervisor执行目标命令时会运行：python3.9 manage.py collectstatic --clear --noinput
若该命令失败（如解释器错误、Django缺失等），uWSGI会崩溃，导致Nginx返回502/404错误。

修复流程（容器内操作）

bash
docker compose exec awx bash  # 进入容器
supervisorctl status  # 查看服务状态
tail -n 200 /var/log/nginx/error.log || true  # 查看Nginx错误日志
# 手动执行collectstatic
python3.9 manage.py collectstatic --clear --noinput

预期输出："121 static files copied to '/var/lib/awx/public/static'."

bash
# 重启uWSGI服务
supervisorctl restart tower-processes:awx-uwsgi
# 检查uWSGI是否监听8050端口
ss -ltnp | grep 8050 || echo "uWSGI not listening yet"
# 检查服务健康状态
curl -sS -i http://127.0.0.1:8050/api/v2/ping/ || echo "ping failed"

若8050端口被占用/卡住：

bash
supervisorctl stop tower-processes:awx-uwsgi || true  # 停止uWSGI
pkill -9 -f 'uwsgi.*tower/uwsgi.ini' || true  # 强制终止uWSGI进程
pkill -9 -x uwsgi || true  # 强制终止残留uWSGI进程
supervisorctl start tower-processes:awx-uwsgi  # 启动uWSGI

仍失败？

• 确保/var/lib/awx/public/static目录可写且已映射至awx_static卷
• 重新执行collectstatic后重启uWSGI
• 检查详细日志：

bash
docker compose logs awx | tail -n 300  # 容器日志
tail -n 200 /var/log/nginx/error.log  # Nginx错误日志

10. 安全注意事项

• 本Compose配置仅用于本地开发/演示，生产环境请使用AWX Operator
• 若需暴露服务至localhost以外的网络，务必修改默认密钥（SECRET_KEY）和密码

11. 镜像信息

• Docker Hub镜像：afsharidevops/awx:23.9.0
• upstream源码：https://github.com/ansible/awx%EF%BC%88%E5%88%86%E6%94%AF/%E6%A0%87%E7%AD%BE23.9.0%EF%BC%89
• 基于tools/docker-compose/_sources工作流构建