瓦力 walle Docker Compose 部署指南

本文以一台真实 Linux 服务器的视角，给出 walle 2.0.1 基于 Docker Compose 的完整部署流程：从目录规划、环境变量、编排文件，到初始化、默认账号登录、端到端发布验证与排障实录。全部命令与回显均在一台干净的 Linux 服务器上实测通过（实测日期 2026-10-25）。

一、前置条件

项目	要求
操作系统	Linux x86_64（内核 3.10+，建议 Ubuntu 20.04/22.04 或 CentOS 7+）
软件依赖	Docker 20.10+ 与 Docker Compose v2（`docker compose` 子命令可用）
硬件	2 核 4 GB 内存起步（walle 本体占用极低，主要开销在 MySQL）
网络端口	Web 端口（本文示例用 8134，可按需改为 80）未被占用
目标机条件	所有发布目标机运行 sshd、可被本机 SSH 免密登录、可访问 git 仓库
git 仓库	支持 http(s)://、git:// 或 ssh:// 协议的任意 git 服务

先在服务器上确认端口未被占用（示例检查 8134）：

$ ss -ltn | grep 8134
$ echo $?
1

无输出即端口空闲。

二、目录规划

建议将编排文件与持久化数据集中在一个目录，本文以 /data/walle 为例：

/data/walle/
├── docker-compose.yml    # 编排文件
├── walle.env             # walle 应用与数据库账号变量
├── db.env                # MySQL 初始化变量
├── ssh-key/              # 部署公私钥（用于免密发布）
└── data/
    ├── mysql/            # 数据库数据
    ├── codebase/         # 代码检出与打包目录
    └── logs/             # walle 运行日志

创建目录：

$ mkdir -p /data/walle/{ssh-key,data/mysql,data/codebase,data/logs} && cd /data/walle

三、编写配置文件

3.1 数据库变量 db.env

MYSQL_ROOT_PASSWORD=walle
MYSQL_DATABASE=walle

3.2 应用变量 walle.env

walle 后端读取的连接变量与 MySQL 初始化变量合并声明（官方示例即此形态）：

MYSQL_USER=root
MYSQL_PASSWORD=walle
MYSQL_DATABASE=walle
MYSQL_ROOT_PASSWORD=walle
MYSQL_HOST=db
MYSQL_PORT=3306

生产环境务必修改两个口令：MYSQL_ROOT_PASSWORD（数据库 root）与 MYSQL_PASSWORD（walle 连库账号），并保持 walle.env 与 db.env 中同名变量一致。

3.3 编排文件 docker-compose.yml

name: walle-2.1-stack

services:
  web:
    image: alenx/walle-web:2.1
    hostname: nginx-web
    ports:
      - "8134:80"
    depends_on:
      - python
    networks:
      - walle-net
    restart: always

  python:
    image: alenx/walle-python:2.1
    hostname: walle-python
    env_file:
      - ./walle.env
    volumes:
      - ./data/codebase/:/tmp/walle/codebase/
      - ./data/logs/:/opt/walle_home/logs/
      - ./ssh-key/:/root/.ssh/
    command: bash -c "cd /opt/walle_home/ && /bin/bash admin.sh migration && python waller.py"
    expose:
      - "5000"
    depends_on:
      - db
    networks:
      - walle-net
    restart: always

  db:
    image: mysql:5.7
    hostname: walle-mysql
    env_file:
      - ./db.env
    command: ['--default-authentication-plugin=mysql_native_password', '--character-set-server=utf8mb4', '--collation-server=utf8mb4_unicode_ci']
    expose:
      - "3306"
    volumes:
      - ./data/mysql:/var/lib/mysql
    networks:
      - walle-net
    restart: always

networks:
  walle-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.58.0/24

要点说明：

web 服务由 Nginx 托管 Vue 前端并反代后端 /api/ 与 /socket.io/，对外只需暴露这一个端口；python（后端 5000）与 db（MySQL 3306）仅在内网互通，不对外监听；
python 服务的 command 在每次启动时先执行数据库迁移再拉起 walle 主程序；
三个持久化目录（MySQL 数据、代码检出目录、日志）与部署公私钥均已挂载到宿主机，重建服务不丢数据；
subnet 用于在宿主机已有多个 Docker 网段时固定网段，若与现有网络冲突请改为空闲网段（可在服务器上先查看已用网段再选择）；
镜像标签 2.1 对应 walle 2.0.1 的发布形态（代码内 VERSION = '2.0.1'）。

四、启动与初始化

4.1 拉起服务

$ cd /data/walle && docker compose up -d
[+] Running 4/4
 ✔ Network walle-2.1-stack_walle-net   Created
 ✔ Container walle-2.1-stack-db-1      Started
 ✔ Container walle-2.1-stack-python-1  Started
 ✔ Container walle-2.1-stack-web-1     Started

4.2 确认迁移完成（重要）

python 服务的启动命令自带迁移步骤，但 MySQL 首次初始化较慢，可能出现「迁移先于数据库就绪」的竞态——这是实测中最常见的首个故障（现象与处理见第八节排障 1）。启动后观察日志确认迁移与主程序均就绪：

$ docker compose logs python | grep -E "Running upgrade|Running on"
Running upgrade  -> 5c4cfd9eec51, 00_init_database
Running upgrade 5c4cfd9eec51 -> 7c99f27ee628, 01_add_project_user_and_user_table
Running upgrade 7c99f27ee628 -> 2bca06a823a0, 02_init_walle_database
Running upgrade 2bca06a823a0 -> 99ac3b879263, 03_update_role
Running upgrade 99ac3b879263 -> 6f9edb80f6b5, 04_update_user_password
Running upgrade 6f9edb80f6b5 -> d6a466b5fe08, 05_add_project_field_repo_mode
Running upgrade d6a466b5fe08 -> 2e8908ee6801, 06_update_task_field_commit_id
 * Running on http://0.0.0.0:5000/ (Press CTRL+C to quit)

7 个迁移版本全部 Running upgrade 且出现 Running on http://0.0.0.0:5000/ 即就绪。若迁移报连接错误，按第八节排障 1 手动补跑。

4.3 验证 Web 可达

$ curl -sI http://127.0.0.1:8134/ | head -1
HTTP/1.1 200 OK

4.4 首次登录并改密

浏览器访问 http://<服务器IP>:8134，使用初始超级管理员登录（实测有效）：

账号：super@walle-web.io
密码：Walle123

登录后立即进入「用户中心」修改密码。若团队需为其他成员开号，由超管在用户管理中创建（示例：admin@quzuo.net / q1w2e3r4，创建后同样要求首次登录改密）。

五、基础配置五步走

首次登录后按以下顺序完成初始化（详细字段说明见《walle v2.0.1 配置参数详解》）：

创建空间：用户中心 → 空间管理 → 新建（如「演示空间」）。walle 的环境、服务器、项目均挂在空间下，新建账号必须先切换到空间才能操作；
创建环境：环境管理 → 新建（如「测试环境」「生产环境」）；
登记目标机：服务器管理 → 新建，填写名称、主机（IP 或可解析主机名）、SSH 用户（常用 root）、端口 22；walle 不会自动下发公钥，需按第六节预置部署公钥；
创建项目：项目管理 → 新建，核心字段：git 仓库地址 repo_url、仓库模式 repo_mode（branch/tag）、目标路径 target_root 与版本目录 target_releases、保留版本数 keep_version_num、是否开启审核 task_audit；
发起上线单：进入项目 → 创建上线单 → 选择分支与 commit → 提交（开审核的项目先送审，审核通过后出现「上线」按钮）。

六、准备目标机与发布验证

6.1 目标机一次性准备

在目标机上：确认 sshd 运行、安装 git；在服务器侧生成专用部署密钥并追加到目标机（路径对应第 3.3 节挂载的 /data/walle/ssh-key/）：

$ ssh-keygen -m PEM -t rsa -b 2048 -f ssh-key/id_rsa -N "" -C "walle-deploy"
$ ssh-copy-id -i ssh-key/id_rsa.pub root@<目标机IP>

两个实测细节必须遵守：

密钥必须是 PEM 格式（-m PEM）：walle 内置的 paramiko 2.4.2 无法读取 OpenSSH 新格式私钥；
目标机 OpenSSH ≥ 8.8 需放行 ssh-rsa 算法（详见排障 3）。

同时目标机需能被 walle 访问 git 仓库：内网自建 git 服务可直接使用；目标机即 git 服务时，在目标机初始化裸仓库（示例）：

$ git init --bare /srv/git/deploy-demo.git

6.2 创建项目并发起首次上线

按第五节完成项目创建（示例：仓库 git://<git主机>/deploy-demo.git，分支模式 branch，target_root=/srv/www/demo-web，target_releases=/srv/www/demo-releases）。上线单创建时 walle 会实时拉取分支与 commit 列表——下拉能出数据即证明 walle 主机到 git 仓库的连通性正常。

提交上线单并点击「上线」，实时日志窗口逐命令回显；完成后在目标机验证：

$ ls -la /srv/www/ | grep demo-web
lrwxrwxrwx 1 root root   42 Oct 25 01:25 demo-web -> /srv/www/demo-releases/1_3_20261025_092433
$ cat /srv/www/demo-web/index.html
<h1>walle deploy demo v1</h1>

二次发布后版本目录保留两份，回滚操作（上线单列表 → 回滚）只是把软链接重新指向上一个版本目录，秒级完成：

$ cat /srv/www/demo-web/index.html
<h1>walle deploy demo v1</h1>   # 回滚后内容由 v2 还原为 v1

七、日常运维

升级：进入后端安装目录执行 bash admin.sh upgrade（详见《walle v2.0.1 常用 CLI 命令详解》）；
备份：每日备份 data/mysql/（或 mysqldump 导出）与项目配置；上线单与发布记录均在数据库中；
日志：错误日志 data/logs/error.log，运行日志由 web 控制台实时查看；
停止/重启：docker compose stop / docker compose restart。

八、排障实录（本站实测沉淀）

1. 迁移报 MySQL 连接错误，服务反复重启 现象：docker compose logs python 反复出现 Migration walle database... Waiting for MySQL 后报 (2003, "Can't connect to MySQL server on 'db' (111)")。原因：MySQL 首次初始化（生成系统表）耗时较长，迁移先于数据库就绪执行且不会自动重试。处理：待 db 服务日志出现 ready for connections 后手动补跑迁移并重启后端：

$ docker compose exec python bash admin.sh migration
$ docker compose restart python

2. 上线单无法选择 commit / 部署报 git reset 失败 现象：部署阶段 git reset --hard 报错退出。原因：上线单缺少 commit 标识（正常界面流程必选 commit；接口调用时若漏传 commit_id 即触发）。处理：创建上线单时必须选定具体 commit 再执行上线。

3. 目标机 SSH 认证失败（OpenSSH 8.8+） 现象：部署日志提示Permission denied 或 Authentication failed，但手动 ssh -i ssh-key/id_rsa root@<目标机> 正常。原因：walle 内置 paramiko 2.4.2 仅支持 ssh-rsa（SHA-1）签名，OpenSSH 8.8 起默认禁用该算法。处理：在目标机 /etc/ssh/sshd_config 追加一行并重载 sshd：

PubkeyAcceptedKeyTypes +ssh-rsa
$ systemctl reload sshd

4. 项目路径配置错误导致发布目录异常 现象：首次发布后目标机路径混乱甚至目录被删除重建。原因：target_root（对外软链接路径）与 target_releases（版本目录）被配成同一路径，或 target_root 提前以实体目录存在——walle 会把 target_root 作为软链接管理。处理：两者必须为不同路径（如 /srv/www/demo-web 与 /srv/www/demo-releases），且首次发布前 target_root 不应预先创建实体目录。

九、小结

本文完成了 walle 2.0.1 的 Compose 部署、初始化与端到端发布/回滚验证。后续阅读：《walle v2.0.1 配置参数详解》逐项解析环境变量与项目字段，《walle v2.0.1 常用 CLI 命令详解》覆盖迁移、升级与服务管理，组件定位与横向对比见《瓦力 walle 介绍与选型指南》。