瓦力 walle 常用 CLI 命令详解

walle 的服务端运维围绕安装目录下的 admin.sh 展开，共 init/start/stop/restart/upgrade/migration 六个子命令。本文全部命令与回显均在真实服务器实测通过（实测日期 2026-10-25，版本 v2.0.1），按「命令总览 → 六大子命令 → 环境自检 → 日志排查 → 数据库取证 → 发布链命令」组织。

一、命令入口与总览

后端安装目录为 /opt/walle_home（官方 Compose 部署与服务内一致）。所有管理命令在该目录下执行：

$ cd /opt/walle_home && bash admin.sh

不带参数调用会打印帮助（实测回显）：

************************************************************
Usage: sh admin {init|start|stop|restart|upgrade|migration}
************************************************************

子命令	用途	使用场景
`init`	裸机首次安装：识别系统并装依赖、建虚拟环境	仅裸机部署首次使用
`migration`	执行数据库迁移（Alembic）	首次部署、升级后
`start`	后台拉起 walle 主程序	日常启服
`stop`	强制停止主程序	日常停服
`restart`	stop + start	改配置后生效
`upgrade`	git 拉取新版本 → 装依赖 → 迁移	版本升级

Compose 部署形态下，以上命令统一通过 docker compose exec python bash -c "cd /opt/walle_home && bash admin.sh <子命令>" 进入执行；裸机部署直接在安装目录执行。下文回显以裸机视角为准。

二、六大子命令详解

2.1 bash admin.sh migration —— 数据库迁移

执行 Alembic 迁移，把库结构升到当前版本（实测回显，共 7 个版本）：

$ bash admin.sh migration
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

两个实测经验：

首次部署时，MySQL 初始化慢于迁移启动会报 Can't connect to MySQL server，待数据库就绪后重新执行本命令即可，无需重建；
迁移成功但主程序未随之恢复时（例如启动脚本竞态），执行 bash admin.sh restart 拉起服务。

2.2 bash admin.sh start —— 启动服务

以 nohup 方式后台运行主程序 waller.py（实测回显）：

$ bash admin.sh start
Starting walle
----------------
Start walle:                 [ ok ]
runtime:  logs/runtime.log
error:  logs/error.log

启动后运行日志写入 logs/runtime.log，错误写入 logs/error.log。可用 ps -ef | grep waller.py 确认进程存在，用浏览器或 curl 验证 80 端口（Nginx 层）可达。

2.3 bash admin.sh stop —— 停止服务

按进程名查找并强制结束主程序（实测回显）：

$ bash admin.sh stop
Stoping walle
----------------
Stop walle:                  [ ok ]

注意两点（实测确认）：

stop 是 kill -9 强杀，不存在优雅退出，生产建议避开发布窗口执行；
Compose 形态下后端服务配置了 restart: always，stop 后进程会被重新拉起（端口随即恢复），这是编排层的自愈行为；如需真正停服，使用 docker compose stop。

2.4 bash admin.sh restart —— 重启服务

等价于依次执行 stop 与 start，适用于修改 walle/config/settings.py（邮箱、日志等）之后生效。

2.5 bash admin.sh upgrade —— 升级版本

升级流程（源码行为，实测目录内执行）：建议先 git stash 暂存本地改动，随后依次执行 git 拉取、依赖安装、数据库迁移，并提示重启：

$ bash admin.sh upgrade
建议先暂存本地修改 git stash，更新后再弹出 git stash pop，处理冲突。

命令完成后按提示 bash admin.sh restart。升级会同时执行 requirement（按 requirements/prod.txt 重装依赖）与 migration（见 2.1），因此升级后无需单独补迁移。

2.6 bash admin.sh init —— 裸机首次安装

仅裸机部署需要：脚本识别系统发行版并安装编译依赖（CentOS 系：mysql-devel/gcc 等；Ubuntu/Debian 系：libmysqld-dev/python-dev 等），随后创建 Python 虚拟环境。官方镜像环境已内置全部依赖，无需执行。

三、环境自检命令

发布前用以下命令确认链路（全部实测）：

# 1. 后端运行时版本（walle 2.x 锁定 Python 2.7）
$ python -V
Python 2.7.16

# 2. walle 主机到 git 仓库连通性（能列出分支哈希即通）
$ git ls-remote git://<git主机>/deploy-demo.git
5acaefa4a7c4b290bf61c7eea7a9fbbf53d85758	HEAD
5acaefa4a7c4b290bf61c7eea7a9fbbf53d85758	refs/heads/master

# 3. walle 主机到目标机 SSH 免密（部署公钥已追加时）
$ ssh -i ~/.ssh/id_rsa root@<目标机> 'hostname && ls /srv/www'
target-server
demo-releases
demo-web

# 4. 目标机 sshd 与 git 就绪
$ ssh root@<目标机> 'pgrep sshd >/dev/null && git --version'
git version 2.34.1

任一步失败即无法发布：第 2 步失败检查仓库协议与网络，第 3 步失败排查公钥与 ssh-rsa 算法（OpenSSH 8.8+ 目标机需在 sshd_config 加 PubkeyAcceptedKeyTypes +ssh-rsa）。

四、日志排查

文件	内容	典型用途
`logs/error.log`	应用异常堆栈（接口 500、部署阶段报错）	定位「上线失败」根因
`logs/runtime.log`	主程序运行输出（admin.sh start 重定向）	判断进程是否存活、启动报错
`logs/info.log`	常规信息日志	例行巡检
界面实时日志	WebSocket 逐命令回显	发布现场观察（首选）

常用组合：

$ tail -f logs/runtime.log                 # 跟踪启动与运行
$ grep -A 12 "Exception on /api/" logs/error.log | tail -14   # 最近一次接口异常堆栈

实测排障经验：上线失败时先看界面实时日志的最后一条命令；若信息不足再查 error.log 中的异常堆栈（例如数据库未就绪的迁移失败、目标机 SSH 认证失败，均有明确堆栈）。

五、数据库取证命令

上线单、发布记录、用户均在 MySQL 的 walle 库中。只读取证常用三查：

# 1. 发布记录：每次执行了哪些命令（walle 自动生成）
$ mysql -uroot -p -e "select stage,sequence,host,status,left(command,70) as cmd
    from walle.records where task_id=3 order by id"

# 2. 上线单状态：branch/commit/操作时间
$ mysql -uroot -p -e "select id,name,status,branch,commit_id,created_at
    from walle.tasks where project_id=1 order by id"

# 3. 核对管理员账号
$ mysql -uroot -p -e "select id,username,email,role from walle.users"
id  username  email                 role
1   Super     super@walle-web.io    SUPER
2   Owner     owner@walle-web.io
3   Master    master@walle-web.io
4   Developer developer@walle-web.io
5   Reporter  reporter@walle-web.io

records 表是排障金矿：每条 command 即 walle 在管理机或目标机实际执行的命令，status 标记该步成败，配合 stage/sequence 可完整还原发布时序。

六、发布链命令速查（walle 自动执行）

walle 发布时自动执行的命令链（实测摘录，路径随项目配置变化），便于理解故障点分布：

# 管理机：检出快照并打包
cd /tmp/walle/codebase/ && cp -rf /tmp/walle/codebase/1 1_3_20261025_092433
cd /tmp/walle/codebase/ && tar zcf /tmp/walle/codebase/1_3_20261025_092433.tgz 1_3_20261025_092433/
scp /tmp/walle/codebase/1_3_20261025_092433.tgz root@<目标机>:/srv/www/demo-releases

# 目标机：解压 → 原子软链切换 → 清理旧版本
cd /srv/www/demo-releases && tar zxf 1_3_20261025_092433.tgz
cd /srv/www/demo-releases && ln -sfn /srv/www/demo-releases/1_3_20261025_092433 /srv/www/demo-releases/current-tmp-3
cd /srv/www/demo-releases && mv -fT /srv/www/demo-releases/current-tmp-3 /srv/www/demo-web
cd /srv/www/demo-releases && find ./ -name "1_*" -print | ls -t | tail -n +6 | xargs rm -rf

运维要点：

mv -fT 原子改名保证软链切换瞬间完成，回滚只是把软链重新指向上一版本目录；
保留版本数由项目配置 keep_version_num 控制（上例保留 5 份，tail -n +6 起删除）；
项目配置的四个自定义钩子（prev_deploy / post_deploy / prev_release / post_release）分别插入检出前后与切换前后执行，重启服务、清缓存等操作写在这里而不是改 walle 代码。

七、常用组合场景

场景	命令序列
首次部署后迁移失败	确认 MySQL 就绪 → `bash admin.sh migration` → `bash admin.sh restart`
修改邮箱/日志配置	编辑 `walle/config/settings*.py` → `bash admin.sh restart`
版本升级	`git stash` → `bash admin.sh upgrade` → `bash admin.sh restart` → `git stash pop`
上线失败排查	界面实时日志 → `tail logs/error.log` → `records` 表取证
服务假死	`bash admin.sh restart`（Compose 形态改用 `docker compose restart`）

部署落地与配置含义分别见《walle v2.0.1 Docker Compose 部署指南》与《walle v2.0.1 配置参数详解》；组件定位与横向对比见《瓦力 walle 介绍与选型指南》。