Warpgate 常用 CLI 命令详解

目标：以 v0.30.2 实机 --help 回显与真实执行结果为底本（2026-10-27），逐条讲清 Warpgate 命令行工具的全部子命令、选项与典型用法，覆盖安装初始化、日常运维、账号恢复与数据库迁移全生命周期。

一、环境信息

服务器：Debian GNU/Linux 12 (bookworm) 12.15，x86_64（环境明细见《Warpgate 安装与初始化实战》第一节）；
软件版本：Warpgate v0.30.2（2026-10-27 官方最新稳定版），二进制位于 /usr/bin/warpgate，配置 /etc/warpgate.yaml；
本篇所有回显均在 systemd 托管运行中的实机上采集，逐行照抄。

二、前置条件

已按安装篇完成安装与初始化；
CLI 操作需要 root（或对 /etc/warpgate.yaml 与数据目录有读写权限的用户）；
setup、recover-access 两个命令要求交互终端（无 TTY 环境会直接报错退出，排障实录见 4.3/4.7 节）。

三、命令总览

warpgate --help

实测回显：

Usage: warpgate [OPTIONS] <COMMAND>

Commands:
  setup             Run first-time setup and generate a config file
  unattended-setup  Run first-time setup non-interactively
  client-keys       Show Warpgate's SSH client keys
  run               Run Warpgate
  check             Perform basic config checks
  create-user       Create a new user
  recover-access    Reset password and auth policy for a user
  copy-database     Copy the current database contents into another database
  migrate-database  Run database migrations
  version           Show version information
  healthcheck       Automatic healthcheck for running Warpgate in a container
  help              Print this message or the help of the given subcommand(s)

Options:
  -c, --config <CONFIG>          [env: WARPGATE_CONFIG=] [default: /etc/warpgate.yaml]
  -d, --debug...                 
      --log-format <LOG_FORMAT>  Log output format (text or json) [possible values: text, json]
      --skip-securing-files      Do not tighten UNIX modes of config and data files
  -h, --help                     Print help

按用途分组：

分组	命令	典型场景
初始化	`setup`、`unattended-setup`	首次安装生成配置
运行	`run`、`healthcheck`	前台启动（systemd 单元内）、容器健康检查
账号	`create-user`、`recover-access`	建用户、管理员找回/重置
密钥	`client-keys`	查看连向目标的客户端公钥
数据库	`check`、`migrate-database`、`copy-database`	配置校验、元库迁移、换库
通用	`version`、`help`	版本与帮助

全局选项（置于子命令之前）：-c/--config 指定配置路径（或环境变量 WARPGATE_CONFIG）、--log-format json 切换日志格式、--skip-securing-files 跳过对配置/数据文件的收紧（chown/chmod）动作、-d 调试日志。

四、核心命令详解

4.1 warpgate setup——交互式首装向导

生成配置文件与全部初始化资产（交互问答流程、逐项问题与默认值见安装篇第五节）。要点：

必须交互终端执行；
全部默认回车即按默认端口初始化（HTTP 8888/SSH 2222/MySQL 33306/PG 55432/K8s 8443，VNC/RDP 不启用），会话录制开启，最后设置 admin 密码；
重新运行会重新生成配置，已有数据目录会被复用。

4.2 warpgate unattended-setup——非交互首装（脚本化首选）

warpgate unattended-setup --help

实测回显：

Run first-time setup non-interactively

Usage: warpgate unattended-setup [OPTIONS]

Options:
      --data-path <DATA_PATH>                        Path to the data directory [default: /var/lib/warpgate]
      --admin-password <ADMIN_PASSWORD>              Admin user's password [env: WARPGATE_ADMIN_PASSWORD=]
      --external-host <EXTERNAL_HOST>                Public host to listen on [default: 0.0.0.0]
      --http-port <HTTP_PORT>                        HTTP port (set to 0 to disable) [default: 8888]
      --ssh-port <SSH_PORT>                          SSH port (set to 0 to disable) [default: 2222]
      --mysql-port <MYSQL_PORT>                      MySQL port (set to 0 to disable) [default: 33306]
      --postgres-port <POSTGRES_PORT>                PostgreSQL port (set to 0 to disable) [default: 55432]
      --kubernetes-port <KUBERNETES_PORT>            Kubernetes port (set to 0 to disable) [default: 55433]
      --vnc-port <VNC_PORT>                          VNC port (set to 0 to disable)
      --rdp-port <RDP_PORT>                          RDP port (set to 0 to disable)
      --record-sessions                              Record user sessions
      --host-key-verification <MODE>                 Target SSH host key verification method (can be set in the config file later) [default: prompt] [possible values: prompt, auto-accept, auto-reject, ignore]
      --database-url <DATABASE_URL>                  Database URL (sqlite:/path, mysql://..., postgres://...)
      --tls-certificate <TLS_CERTIFICATE>            TLS certificate path
      --tls-key <TLS_KEY>                            TLS key path
      --recordings-path <RECORDINGS_PATH>            Session recordings directory
      --recordings-enable <RECORDINGS_ENABLE>        [default: true]
  -h, --help                                         Print help

要点与坑：

不传的端口参数即不启用该监听器（如完全不想要 MySQL 代理就别传 --mysql-port）；
注意与交互向导的默认差异：K8s 默认端口交互向导是 8443，而 unattended-setup 帮助里是 55433，安装篇实测显式传了 --kubernetes-port 8443；
--database-url 可直接初始化到外置 MySQL/PostgreSQL 元库；
--admin-password 不传时改读环境变量 WARPGATE_ADMIN_PASSWORD，避免密码进 shell 历史；
完整初始化回显（含生成的配置全文）见安装篇 4.2 节。

4.3 warpgate run——前台运行

warpgate run --help

实测回显：

Run Warpgate

Usage: warpgate run [OPTIONS]

Options:
      --enable-admin-token  Enable an API token (passed via the `WARPGATE_ADMIN_TOKEN` env var) that automatically maps to the first admin user
  -h, --help                Print help

生产上不手动跑，交给 systemd（单元文件见安装篇 4.4 节）；--enable-admin-token 用于自动化集成——运行期从 WARPGATE_ADMIN_TOKEN 环境变量读取一个 API 令牌并映射到首个 admin 用户，脚本可凭它调管理 API。

4.4 warpgate check——配置校验

warpgate check

实测回显：

27.10.2026 07:37:15  INFO warpgate::config: Using config: "/etc/warpgate.yaml"
27.10.2026 07:37:15  INFO warpgate::commands::check: No problems found

改配置后的标准动作：check → restart。校验失败会指明具体字段（如端口非法、证书路径不存在）。

4.5 warpgate create-user——创建用户

warpgate create-user --help

实测回显：

Create a new user

Usage: warpgate create-user [OPTIONS] <USERNAME>

Arguments:
  <USERNAME>  

Options:
  -p, --password <PASSWORD>  Password (required if WARPGATE_NEW_USER_PASSWORD env var is not set)
  -r, --role <ROLE>          
  -h, --help                 Print help

实测：创建 dba 用户、设密码、直接挂到既有角色 ops-team：

warpgate create-user dba -p q1w2e3r4 -r ops-team

实测回显：

27.10.2026 07:52:10  INFO warpgate::config: Using config: "/etc/warpgate.yaml"
27.10.2026 07:52:10  INFO warpgate::commands::create_user: Created user "dba"

经管理 API 复核，dba 已在用户列表（节选）：

{"allowed_ip_ranges":null,"credential_policy":{"http":null,...},"description":null,"id":"3ea0d09a-a0a2-4b0c-8e12-fd1a1c9e5e19","username":"dba"}

要点：-r 挂角色要求该角色已存在（角色在管理台/API 建）；密码也可经 WARPGATE_NEW_USER_PASSWORD 环境变量传入，避免进历史记录；角色与目标细粒度授权、OTP 双因素等仍需在管理台完成（CLI 只覆盖最小闭环）。

4.6 warpgate client-keys——查看 SSH 客户端公钥

Warpgate 连向 SSH 目标用的是自己生成的客户端密钥对。把公钥加进目标机 authorized_keys，即可用密钥认证（目标侧免密、Warpgate 侧不存目标密码）：

warpgate client-keys

实测回显（公钥内容随机每机不同，以下为实机输出）：

27.10.2026 07:54:37  INFO warpgate::config: Using config: "/etc/warpgate.yaml"
Warpgate SSH client keys:
(add these to your target's authorized_keys file)

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIM13tWuvM4rxCyTgAYstLxKHxMe367jSCcmqhk+N/ReF client-ed25519 (default)
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDFoBDb1SXyfV8ArYaPeNhXdoyvDtzrkXIz0HbeNt8n4+Yx5slTXCsTQkb6f98QDMjCPicnTb3LeyajSDEyR4BO+XDUgx6DEyRl1ZBcatodVLaNWsOXhYanIj3P3pnCdbRdkqa1AeQvaGXIg8vT5hMNb0kEPshFKtRVd1oCT8qEqnmt+3i8pkn1o9ZSSHwpfJ8zQiWmzoiEHoNym3jP9sk0D18R2GP1TqjtO1C/8mYtmEDcFso7j8jy7DTzpVihtNQj4BDBB+1OXqH984XesEYzW1/P5c6EwAb7Ii46mwg7fAP8xmtJsVww1sFrivlWDUQcudkufO76Nhc9+z4TdlVR+PHVFGz5wjq+gn2jLdzCJHVOWQe+zN+zKG5/LVD+P+YeV8lR8jqeaxp2i3dWUkT63n4NApuMVMEY03tFxLagThlXsexnPF1zRC8+FurZQtd0KvuS/Bvh4aKC0eXCgSDF6c882T0LqUmUzVDSo+GpuM/2LGAMPwaRlQUIYjBtCdCeosH6JkfNgxKqxQzVsR7OlrdFj7PVxehdEk+Ot4YiJQOTz2a8ZS+vfrXPmYnkQjXnGCcv+oJGMY+1iB6OkKGKITAEIFWdaU5lrksWIP/GcsYh3aTviw7z9s6Q105wOBk11Kbnj1Xa5s6vrc5eLZzYtYHtAW8TkwzDCuECGFFe7w== client-rsa (default)

标准流程：输出两把（Ed25519/RSA）→ 在目标机 authorized_keys 追加 Ed25519 公钥 → 目标（Target）的认证方式从 Password 改为 PublicKey（管理台或 API）。

4.7 warpgate recover-access——管理员找回

忘记 admin（或任意用户）密码/被登录保护锁死时的救援命令，交互式重置密码与认证策略：

warpgate recover-access [USERNAME]

选项仅 -h/--help（重置密码在交互问答中输入）。

排障实录：非交互环境实测必报错——管道喂密码也不行：

$ echo -e "q1w2e3r4" | warpgate recover-access appdev
... Please run this command from an interactive terminal.

处理：到真实 TTY 执行；无人值守场景无此命令的替代品（它本质是「应急人工介入」入口，设计上就该走交互）。

4.8 warpgate copy-database——元库迁移

把当前 database_url 指向的库内容完整复制到目标库（SQLite→MySQL/PG、或换实例的迁移专用）：

warpgate copy-database --help

实测回显：

Copy the current database contents into another database

Usage: warpgate copy-database <TARGET_URL>

Arguments:
  <TARGET_URL>  Target database URL

Options:
  -h, --help  Print help

用法示例（先停写，再复制，最后改配置指向新库）：

systemctl stop warpgate
warpgate copy-database "postgres://warpgate:CHANGE_ME@pg-db.internal:5432/warpgate"
# 编辑 /etc/warpgate.yaml：database_url 改为新库
warpgate check && systemctl start warpgate

⚠️ 注意：复制的是元数据库（用户/目标/角色/会话记录），不包含 recordings/ 目录里的录制文件——换库迁移时录制目录要一并搬家（改 recordings.path 或整体拷贝数据目录）。

4.9 warpgate migrate-database——元库结构升级

warpgate migrate-database --help

实测回显：

Run database migrations

Usage: warpgate migrate-database [OPTIONS] [STEPS]

Arguments:
  [STEPS]  Number of migrations to apply (positive) or revert (negative) [default: 1]

Options:
      --destructive  
  -h, --help         Print help

升级二进制后首次 run 会自动跑全部待执行迁移；此命令用于手动控制步数（正数向前 N 步、负数回退 N 步）。--destructive 允许破坏性变更（回退部分版本需要），生产务必先备份元库再执行。

4.10 warpgate version 与 healthcheck

warpgate version

实测回显：

warpgate v0.30.2

warpgate healthcheck

实测回显：

27.10.2026 07:54:37  INFO warpgate::config: Using config: "/etc/warpgate.yaml"

退出码 0。healthcheck 主要给容器用（官方 Docker 镜像的 HEALTHCHECK 指令即是它）：能正常读配置、完成基础检查即健康；systemd 部署可作为监控脚本探针。

五、实战速查：三分钟常见操作

# 改配置后的标准三连
warpgate check && systemctl restart warpgate && warpgate healthcheck

# 无人值守重装初始化（保留 admin 密码不进历史）
WARPGATE_ADMIN_PASSWORD='q1w2e3r4' warpgate unattended-setup \
  --data-path /var/lib/warpgate --http-port 8888 --ssh-port 2222 \
  --record-sessions --host-key-verification auto-accept

# 建用户并挂角色
warpgate create-user deployer -p 'q1w2e3r4' -r ops-team

# 目标机改密钥认证：先取客户端公钥
warpgate client-keys

# SQLite → PostgreSQL 迁移
systemctl stop warpgate
warpgate copy-database "postgres://warpgate:CHANGE_ME@db:5432/warpgate"
sed -i 's#^database_url:.*#database_url: postgres://warpgate:CHANGE_ME@db:5432/warpgate#' /etc/warpgate.yaml
warpgate check && systemctl start warpgate

六、常见问题

Q1：setup/recover-access 报 "Please run this command from an interactive terminal." 这两个命令依赖 TTY（实测回显见 4.7 节），脚本/管道方式必然失败；初始化改 unattended-setup，找回密码上真实控制台。

Q2：create-user 提示密码必填？ -p 与环境变量 WARPGATE_NEW_USER_PASSWORD 二选一；批量建号用后者，防止密码进 shell history。

Q3：copy-database 复制后用户能登录但目标连不上？ 大概率目标凭证（Password/PublicKey）随库迁过去了、但 SSH 客户端密钥没随库迁移——到新机上重跑 warpgate client-keys 核对公钥是否与目标机 authorized_keys 一致；录制文件按 4.8 节 ⚠️ 说明单独搬。

Q4：升级新版本后启动报数据库迁移错误？ 先 warpgate migrate-database（自动补齐迁移步数）；需回退版本时用负数步数 + --destructive，执行前备份元库。

Q5：--log-format json 与配置里 log.format 冲突以谁为准？ 命令行全局选项覆盖配置文件，临时排查时用命令行参数、长期方案改配置文件。

七、参考链接

本专栏：《Warpgate 介绍与选型指南》、《Warpgate 安装与初始化实战》、《Warpgate 配置参数详解》；
官方文档站（CLI 相关专题：Systemd、Backup & restore、Upgrading 等）：https://warpgate.null.page/
Releases（版本与二进制）：https://github.com/warp-tech/warpgate/releases