Warpgate 安装与初始化实战

目标：在一台 Debian 12 服务器上以官方 Release 单二进制方式完成 Warpgate v0.30.2 的安装、unattended-setup 初始化、systemd 托管与 Web 管理台验证，并实战完成「目标机接入 → 用户授权 → SSH/HTTP 双形态穿透 → 会话录制核验」的完整闭环；所有命令与回显均来自真实服务器实测（2026-10-27）。

一、环境信息

本篇实测涉及两台内网服务器，角色与配置如下：

角色	操作系统	内网 IP	主机名	配置
Warpgate 堡垒机（本文主服务器）	Debian GNU/Linux 12 (bookworm)，12.15	10.89.56.10	warpgate	x86_64，6 核，19Gi 内存，磁盘 443G
内网目标机（被代理的服务器）	Ubuntu 22.04.5 LTS	10.89.56.20	target01	运行 sshd 与 nginx

uname -m
cat /etc/debian_version
nproc
free -h | head -2
df -h / | tail -1

实测回显（Warpgate 服务器）：

x86_64
12.15
6
               total        used        free      shared  buff/cache   available
Mem:            19Gi       8.5Gi       1.6Gi       143Mi       9.9Gi        10Gi
overlay         443G  124G  301G  30% /

软件版本：Warpgate v0.30.2（撰写时官方最新稳定版，2026-10-27 实查 GitHub Releases）。

二、前置条件

2.1 系统与硬件

Linux x86_64 或 arm64（Release 提供 warpgate-v0.30.2-x86_64-linux 与 warpgate-v0.30.2-arm64-linux 两个裸二进制）；
无任何运行时依赖：Warpgate 是静态单二进制，不要求预装数据库、解释器或额外库；
资源占用极低：实测 systemd 托管运行时常驻内存约 9.5MiB（见 4.5 节 status 回显），1C1G 虚机即可承载中小规模接入。

2.2 端口规划

安装向导/初始化参数中会逐项确认各协议监听端口，默认值与本文实测取值如下：

协议监听器	默认端口	本文实测	说明
HTTP（管理台 + Web 代理）	8888	8888	必开，管理台与 HTTP 目标代理共用
SSH	2222	2222	开启 SSH 接入时启用
MySQL	33306	33306	数据库代理
PostgreSQL	55432	55432	数据库代理
Kubernetes	8443	8443	kube-apiserver 代理
VNC	5900	未启用	远程桌面
RDP	3389	未启用	远程桌面

生产部署建议按需收敛：只开放实际使用的监听器，其余在初始化时不开（非交互模式下不传对应 --xx-port 参数即不启用）。

2.3 网络与防火墙

Warpgate 服务器需能访问所有目标机的目标端口（本篇为 10.89.56.20 的 22/80）；
客户端需能访问 Warpgate 的各监听端口；
若部署在防火墙后，放行上表端口；HTTPS 管理台务必放行 8888（或自定义端口）。

三、版本选型说明

2026-10-27 实查 GitHub Releases：https://github.com/warp-tech/warpgate/releases/latest 重定向至 tag/v0.30.2，即当前最新稳定版。v0.30 线相对早期版本（如 v0.6~v0.9 时代）的显著变化：

协议面扩展至七类（新增 Kubernetes、PostgreSQL、VNC、RDP 监听器）；
CLI 子命令收敛（详见《Warpgate 常用 CLI 命令详解》），初始化命令为 setup / unattended-setup；
管理台按用户侧与管理侧拆分 OpenAPI，新增目标分组、密钥后端（Vault/OpenBao）、登录保护、会话审批等模块。

v0.30.2 Release 附件清单（expanded_assets 页实查）：

附件	用途
warpgate-v0.30.2-x86_64-linux	x86_64 裸二进制（本文使用）
warpgate-v0.30.2-arm64-linux	arm64 裸二进制
warpgate-v0.30.2-x86_64-linux.cdx.xml	x86_64 SBOM（CycloneDX）
warpgate-v0.30.2-arm64-linux.cdx.xml	arm64 SBOM

四、方案一：官方 Release 二进制安装（推荐主线）

4.1 下载二进制

在 Warpgate 服务器上直接下载 Release 裸二进制：

curl -fL -o /usr/bin/warpgate \
  "https://github.com/warp-tech/warpgate/releases/download/v0.30.2/warpgate-v0.30.2-x86_64-linux"
chmod +x /usr/bin/warpgate

⚠️ 网络说明：GitHub 直连在部分网络环境缓慢或不稳定。本环境实测采用 HTTP 代理下载成功（curl -fL -x http://192.168.1.62:7897 -o ...），完整文件大小约 105MB；下载后可用 warpgate version 验证产物完整性。若代理不可用，可从国内镜像加速站点获取同名 Release 附件。

版本验证：

warpgate version

实测回显：

warpgate v0.30.2

4.2 非交互初始化（unattended-setup）

官方提供两种初始化路径：交互式 warpgate setup 与非交互 warpgate unattended-setup。无人值守/脚本化部署直接用后者，参数一次性给全：

warpgate unattended-setup \
  --data-path /var/lib/warpgate \
  --http-port 8888 \
  --ssh-port 2222 \
  --mysql-port 33306 \
  --postgres-port 55432 \
  --kubernetes-port 8443 \
  --record-sessions \
  --host-key-verification auto-accept \
  --admin-password q1w2e3r4 \
  --external-host 10.89.56.10

💡 技术拓展：--host-key-verification 控制 Warpgate 作为 SSH 客户端连向目标机时对「目标主机密钥」的校验策略，共四档——prompt（默认，运行中交互确认）、auto-accept（首次自动接受并记录，适合初始化阶段）、auto-reject（拒绝未知密钥）、ignore（不校验）。生产环境建议目标密钥固化后改回 prompt 或用管理台 known-hosts 功能预先登记，防止目标机被替换后堡垒机仍照连不误。

实测回显（完整照抄，含生成的配置全文）：

27.10.2026 07:25:03  INFO warpgate::commands::setup: Welcome to Warpgate v0.30.2
27.10.2026 07:25:03  INFO warpgate::commands::setup: Let's do some basic setup first.
27.10.2026 07:25:03  INFO warpgate::commands::setup: The new config will be written in /etc/warpgate.yaml.
27.10.2026 07:25:03  INFO warpgate::commands::setup: Generated configuration:
sso_providers: []
external_host: 10.89.56.10
database_url: sqlite:/var/lib/warpgate/db
ssh:
  enable: true
  listen: '[::]:2222'
  proxy_protocol: false
  external_port: null
  external_host: null
  host_key_verification: auto_accept
  inactivity_timeout: 5m
  keepalive_interval: null
  target_handshake_timeout: 30s
http:
  listen: '[::]:8888'
  proxy_protocol: false
  external_port: null
  external_host: null
  certificate: /var/lib/warpgate/tls.certificate.pem
  key: /var/lib/warpgate/tls.key.pem
  trust_x_forwarded_headers: false
  session_max_age: 30m
  cookie_max_age: 1day
  sni_certificates: []
kubernetes:
  enable: true
  listen: '[::]:8443'
  proxy_protocol: false
  external_port: null
  external_host: null
  certificate: /var/lib/warpgate/tls.certificate.pem
  key: /var/lib/warpgate/tls.key.pem
  session_max_age: 30m
mysql:
  enable: true
  listen: '[::]:33306'
  proxy_protocol: false
  external_port: null
  external_host: null
  certificate: /var/lib/warpgate/tls.certificate.pem
  key: /var/lib/warpgate/tls.key.pem
  advertised_version: 8.0.3-Warpgate
postgres:
  enable: true
  listen: '[::]:55432'
  proxy_protocol: false
  external_port: null
  external_host: null
  certificate: /var/lib/warpgate/tls.certificate.pem
  key: /var/lib/warpgate/tls.key.pem
vnc:
  enable: false
  listen: '[::]:5900'
  proxy_protocol: false
  external_port: null
  external_host: null
  certificate: /var/lib/warpgate/tls.certificate.pem
  key: /var/lib/warpgate/tls.key.pem
  enable_ard_auth: false
rdp:
  enable: false
  listen: '[::]:3389'
  proxy_protocol: false
  external_port: null
  external_host: null
  certificate: /var/lib/warpgate/tls.certificate.pem
  key: /var/lib/warpgate/tls.key.pem
log:
  retention: 7days
  audit_retention: 11months 30days 3h 50m 24s
  send_to: null
  format: text

27.10.2026 07:25:03  INFO warpgate::commands::setup: Saved into /etc/warpgate.yaml
27.10.2026 07:25:03  INFO warpgate::config: Using config: "/etc/warpgate.yaml"
27.10.2026 07:25:03  INFO warpgate_db_migrations::m00027_ca: Generating root CA certificate
27.10.2026 07:25:03  INFO warpgate::config: Using config: "/etc/warpgate.yaml"
27.10.2026 07:25:03  INFO warpgate_protocol_ssh::keys: Generating SSH host key (Ed25519)
27.10.2026 07:25:03  INFO warpgate_protocol_ssh::keys: Generating SSH host key (Rsa)
27.10.2026 07:25:04  INFO warpgate_protocol_ssh::keys: Generating SSH client key (Ed25519)
27.10.2026 07:25:04  INFO warpgate_protocol_ssh::keys: Generating SSH client key (Rsa { hash: Some(Sha512) })
27.10.2026 07:25:04  INFO warpgate::commands::setup: Generating a TLS certificate
27.10.2026 07:25:04  INFO warpgate::commands::setup: 
27.10.2026 07:25:04  INFO warpgate::commands::setup: Admin user credentials:
27.10.2026 07:25:04  INFO warpgate::commands::setup:   * Username: admin
27.10.2026 07:25:04  INFO warpgate::commands::setup:   * Password: <your password>
27.10.2026 07:25:04  INFO warpgate::commands::setup: 
27.10.2026 07:25:04  INFO warpgate::commands::setup: You can now start Warpgate with:
27.10.2026 07:25:04  INFO warpgate::commands::setup:   warpgate --config /etc/warpgate.yaml run

初始化过程中自动完成五件事：写配置 /etc/warpgate.yaml、初始化 SQLite 数据库、生成根 CA 与 TLS 证书、生成 SSH 主机密钥（Ed25519+RSA）与客户端密钥、创建管理员用户 admin（密码即 --admin-password 传入值，本例 q1w2e3r4）。

💡 技术拓展：Warpgate 的 TLS 是「双证书」结构——一对自签服务器证书（tls.certificate.pem/tls.key.pem，默认被 HTTP/K8s/MySQL/PG/VNC/RDP 六个监听器共用，可逐监听器替换）与一个由初始化生成的根 CA（用于内部签发，如 MySQL/PG 协议的按域证书）。对外正式服务时把服务器证书换成受信 CA 签发证书即可，管理台与各协议端口无需再改别的配置。

4.3 生成产物清单

ls -la /var/lib/warpgate/

实测回显：

total 24
drwxr-xr-x 3 root root 4096 Oct 27 07:25 .
drwxr-xr-x 1 root root 4096 Oct 27 07:16 ..
drwx------ 2 root root 4096 Oct 27 07:25 db
-rw------- 1 root root  558 Oct 27 07:25 tls.certificate.pem
-rw------- 1 root root  241 Oct 27 07:25 tls.key.pem

产物	说明
`/etc/warpgate.yaml`	主配置文件（生成时首行带 yaml-language-server schema 引用，编辑器可自动补全）
`/var/lib/warpgate/db/`	SQLite 数据库目录（用户/目标/角色/会话元数据）
`/var/lib/warpgate/tls.certificate.pem` / `tls.key.pem`	自签 TLS 服务器证书与私钥（权限 600）
SSH 主机/客户端密钥	存于数据库内，`warpgate client-keys` 可打印客户端公钥

4.4 systemd 托管

写入服务单元 /etc/systemd/system/warpgate.service：

[Unit]
Description=Warpgate
After=network.target

[Service]
ExecStart=/usr/bin/warpgate --config /etc/warpgate.yaml run
ExecReload=/bin/kill -HUP $MAINPID
Restart=always
User=root

[Install]
WantedBy=multi-user.target

启用并启动：

systemctl daemon-reload
systemctl enable --now warpgate.service
systemctl status warpgate.service --no-pager -l | head -18

实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/warpgate.service → /etc/systemd/system/warpgate.service.
● warpgate.service - Warpgate
     Loaded: loaded (/etc/systemd/system/warpgate.service; enabled; preset: enabled)
     Active: active (running) since Tue 2026-10-27 07:25:19 UTC; 4s ago
   Main PID: 370 (warpgate)
      Tasks: 25 (limit: 3172)
     Memory: 9.5M
        CPU: 50ms
     CGroup: /system.slice/warpgate.service
             └─370 /usr/bin/warpgate --config /etc/warpgate.yaml run

Oct 27 07:25:19 warpgate warpgate[370]: 27.10.2026 07:25:19  INFO warpgate::commands::run: Warpgate version=v0.30.2
Oct 27 07:25:19 warpgate warpgate[370]: 27.10.2026 07:25:19  INFO warpgate::config: Using config: "/etc/warpgate.yaml"
Oct 27 07:25:19 warpgate warpgate[370]: 27.10.2026 07:25:19  INFO warpgate_core::cluster: Joined cluster node_id=26dd8132-9b4c-4d62-9951-95e5e90e0db1 address=10.89.56.10:8888
Oct 27 07:25:20 warpgate warpgate[370]: 27.10.2026 07:25:20  INFO warpgate::listener_supervisor: Binding listener name="SSH" endpoint=[::]:2222
Oct 27 07:25:20 warpgate warpgate[370]: 27.10.2026 07:25:20  INFO warpgate::listener_supervisor: Binding listener name="HTTP" endpoint=[::]:8888
Oct 27 07:25:20 warpgate warpgate[370]: 27.10.2026 07:25:20  INFO warpgate_protocol_http: Cookie domain configured: .10.89.56.10 (base host: 10.89.56.10) - cookies will work for 10.89.56.10 and all its subdomains
Oct 27 07:25:20 warpgate warpgate[370]: 27.10.2026 07:25:20  INFO warpgate::listener_supervisor: Binding listener name="PostgreSQL" endpoint=[::]:55432
Oct 27 07:25:20 warpgate warpgate[370]: 27.10.2026 07:25:20  INFO warpgate::listener_supervisor: Binding listener name="Kubernetes" endpoint=[::]:8443

要点：Memory: 9.5M 印证单二进制轻量形态；启动日志逐个绑定监听器，若某端口被占用会在这一段出现明确报错。Joined cluster node_id=... 说明 v0.30 内建集群机制已默认激活本节点。

4.5 Web 管理台初始化验证

用 curl 在本机验证管理台与登录接口（自签证书需 -k）：

curl -sk -o /dev/null -w "%{http_code}\n" https://127.0.0.1:8888/@warpgate/admin
curl -sk -c /tmp/wg-cookies.txt -X POST -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"q1w2e3r4"}' \
  -w "\nHTTP %{http_code}\n" https://127.0.0.1:8888/@warpgate/api/auth/login

实测回显：

200

HTTP 201

/@warpgate/admin 返回 200（管理台页面），登录接口返回 201 且会话 Cookie 已写入。浏览器访问 https://10.89.56.10:8888/@warpgate/admin，以 admin / q1w2e3r4 登录即可进入管理台；首次打开会出现引导页，按需跳过即可。

五、方案二：交互式安装向导（warpgate setup）

在带终端的会话中运行 warpgate setup，向导会依次询问以下各项（问答项与默认值整理自官方文档站《Getting started (binary)》，查询日期 2026-10-27）：

✔ Directory to store app data (up to a few MB) in · /var/lib/warpgate
✔ Endpoint to listen for HTTP connections on · [::]:8888
✔ Accept SSH connections? · yes
✔ Endpoint to listen for SSH connections on · [::]:2222
✔ Accept MySQL connections? · yes
✔ Endpoint to listen for MySQL connections on · [::]:33306
✔ Accept PostgreSQL connections? · yes
✔ Endpoint to listen for PostgreSQL connections on · [::]:55432
✔ Accept Kubernetes connections? · yes
✔ Endpoint to listen for Kubernetes connections on · [::]:8443
✔ Accept VNC connections? · no
✔ Accept RDP connections? · no
✔ Do you want to record user sessions? · yes
✔ Set a password for the Warpgate admin user · ********

回车确认默认值即可走完全程；结束后同样生成 /etc/warpgate.yaml 与密钥，并用 warpgate --config /etc/warpgate.yaml run 启动。若要重新开始，删除或移走配置文件后再次运行 warpgate setup。

排障实录：非交互终端下运行 setup 报错

在无 TTY 的会话（如脚本、远程执行通道）中运行 warpgate setup 或 warpgate recover-access，实测报错并退出：

27.10.2026 07:22:45 ERROR warpgate::commands::common: Please run this command from an interactive terminal.

原因：这两个命令的密码输入与问答交互依赖真实终端（termios），管道喂入也会被拒绝。处理：改在有 TTY 的终端执行；无人值守场景改用 warpgate unattended-setup（密码经 --admin-password 或 WARPGATE_ADMIN_PASSWORD 环境变量传入）。

六、方案三：容器化与源码编译形态（简述）

官方对二进制之外的三种形态均有正式路径，本文以二进制为主线，此处仅给选型提示：

Docker：官方文档站提供《Getting started on Docker》专页，镜像内用 warpgate healthcheck 做健康检查；
Helm / Kubernetes Operator：官方文档站提供 Helm 与 Operator 两个 k8s 部署页，适合已在 k8s 体系内运营的团队；
源码编译（README）：需要 Rust、NodeJS 与 NPM，用 just 组织任务（just npm install → just npm run build → cargo build），产物在 target/{debug|release}，适合二次开发或特殊架构自编。

七、安装方案对比与选择建议

方案	适用场景	优点	注意点
Release 二进制 + systemd（本文主线）	物理机/虚机直接承载，追求极简	零依赖、内存占用个位数 MB、升级即换二进制	需自管 systemd 单元与证书
Docker	已有容器平台，试验快速起停	环境隔离、healthcheck 内建	数据目录需挂载持久化
Helm/Operator	k8s 体系	声明式管理、随集群自愈	需集群与 chart 运维能力
源码编译	二次开发/冷门架构	可改可编	需 Rust+Node 工具链，构建耗时

生产建议：虚机/物理机直接用二进制 + systemd；容器平台用官方 Docker 路径；k8s 重度用户用 Operator。三种形态的配置文件与数据库结构完全一致，后续迁移成本低。

八、初始化后配置说明

初始化生成的两块核心资产（参数逐项详解见《Warpgate 配置参数详解》）：

/etc/warpgate.yaml：进程级配置，顶层为 sso_providers、external_host、database_url 与六个协议监听器段（ssh/http/kubernetes/mysql/postgres/vnc/rdp）及 log 段；本篇初始化产物全文见 4.2 节回显；
/var/lib/warpgate/：数据目录，含 SQLite 数据库、TLS 证书、SSH 密钥与运行期新增的会话录制文件（recordings/<会话ID>/<目标会话ID>/index.ndjson + data.ndjson，见 9.10 节）。

修改配置后执行 warpgate check 做语法与基本校验（实测回显 No problems found），再 systemctl restart warpgate 生效。

九、实战：目标、用户与首次接入

9.1 准备一台内网目标机

目标机 10.89.56.20（Ubuntu 22.04.5 LTS）上确认 sshd 与 nginx 均在运行：

systemctl is-active ssh nginx

实测回显（目标机）：

active
active

给 Web 根目录放一个标识页，便于后面验证 HTTP 代理穿透：

echo "web-hello-from-target-10.89.56.20" > /var/www/html/index.html

目标机 SSH 账号使用 root，密码 q1w2e3r4（示例环境演示值）。

9.2 管理台 API 登录

Warpgate 的管理动作既可在 Web UI 完成，也可走管理 API（/@warpgate/admin/api，OpenAPI 规范在 /@warpgate/admin/api/openapi.json）。本节用 API 演示全流程（脚本化友好），Web UI 中对应页面为 Targets / Roles / Users。

curl -sk -c /tmp/wg-cookies.txt -X POST -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"q1w2e3r4"}' \
  -w "\nHTTP %{http_code}\n" https://127.0.0.1:8888/@warpgate/api/auth/login

实测回显：


HTTP 201

9.3 创建角色

curl -sk -b /tmp/wg-cookies.txt -H "Content-Type: application/json" \
  -X POST https://127.0.0.1:8888/@warpgate/admin/api/roles \
  -d '{"name": "ops-team", "description": "Ops team access", "is_default": false}' \
  -w "\nHTTP %{http_code}\n"

实测回显（节选）：

{"description":"Ops team access","id":"50e42bf7-09ef-4c23-bbb0-545f478b6595","is_default":false,"name":"ops-team"}
HTTP 201

9.4 创建 SSH 目标 web-01

curl -sk -b /tmp/wg-cookies.txt -H "Content-Type: application/json" \
  -X POST https://127.0.0.1:8888/@warpgate/admin/api/targets \
  -d '{
    "name": "web-01",
    "description": "Web server SSH target",
    "options": {"kind": "Ssh", "host": "10.89.56.20", "port": 22, "username": "root", "allow_insecure_algos": false, "auth": {"kind": "Password", "password": "q1w2e3r4"}},
    "ticket_requests_disabled": false,
    "ticket_require_approval": false,
    "require_approval": false
  }' -w "\nHTTP %{http_code}\n"

实测回显（节选）：

{"allow_roles":[],"description":"Web server SSH target","group_id":null,"id":"b57711fa-eae1-4cd8-9c62-dfacb6010755","name":"web-01","options":{"allow_insecure_algos":false,"auth":{"kind":"Password","password":"q1w2e3r4"},"host":"10.89.56.20","jump_host":null,"kind":"Ssh","port":22,"username":"root"}}
HTTP 201

💡 技术拓展：目标（Target）是 Warpgate 的核心抽象，kind 共七种（Ssh/Http/Kubernetes/MySql/Postgres/Vnc/Rdp），每种有独立 options 结构——SSH 目标携带连向目标的用户名与认证方式（Password/PublicKey/Certificate），HTTP 目标携带 URL 与 TLS 校验模式（Disabled/Preferred/Required）。目标凭证保存在 Warpgate 数据库中，用户侧永远接触不到。

9.5 创建 HTTP 目标 intranet-portal

curl -sk -b /tmp/wg-cookies.txt -H "Content-Type: application/json" \
  -X POST https://127.0.0.1:8888/@warpgate/admin/api/targets \
  -d '{
    "name": "intranet-portal",
    "description": "Intranet web portal",
    "options": {"kind": "Http", "url": "http://10.89.56.20:80", "tls": {"mode": "Disabled", "verify": false}, "headers": {}},
    "ticket_requests_disabled": false,
    "ticket_require_approval": false,
    "require_approval": false
  }' -w "\nHTTP %{http_code}\n"

实测回显（节选）：

{"allow_roles":[],"description":"Intranet web portal","group_id":null,"id":"6435b148-7014-4466-8788-33543b2c3956","name":"intranet-portal","options":{"external_host":null,"headers":{},"kind":"Http","tls":{"mode":"Disabled","verify":false},"url":"http://10.89.56.20:80"}}
HTTP 201

9.6 把两个目标授权给角色

SSH_T=b57711fa-eae1-4cd8-9c62-dfacb6010755
HTTP_T=6435b148-7014-4466-8788-33543b2c3956
ROLE=50e42bf7-09ef-4c23-bbb0-545f478b6595
curl -sk -b /tmp/wg-cookies.txt -X POST "https://127.0.0.1:8888/@warpgate/admin/api/targets/$SSH_T/roles/$ROLE" -w " HTTP %{http_code}\n"
curl -sk -b /tmp/wg-cookies.txt -X POST "https://127.0.0.1:8888/@warpgate/admin/api/targets/$HTTP_T/roles/$ROLE" -w " HTTP %{http_code}\n"

实测回显：

 HTTP 201
 HTTP 201

9.7 创建用户 appdev 并授权

创建用户（Web UI 在 Users 页点 Add user）：

curl -sk -b /tmp/wg-cookies.txt -H "Content-Type: application/json" \
  -X POST https://127.0.0.1:8888/@warpgate/admin/api/users \
  -d '{"username": "appdev", "description": "App developer"}' -w "\nHTTP %{http_code}\n"

实测回显（节选）：

{"allowed_ip_ranges":null,"credential_policy":{"http":null,"kubernetes":null,"mysql":null,"postgres":null,"rdp":null,"ssh":null,"vnc":null},"description":"App developer","id":"7900f03b-127b-4fef-9800-20ce9c233c69","username":"appdev"}
HTTP 201

设置密码：

curl -sk -b /tmp/wg-cookies.txt -H "Content-Type: application/json" \
  -X POST "https://127.0.0.1:8888/@warpgate/admin/api/users/7900f03b-127b-4fef-9800-20ce9c233c69/credentials/passwords" \
  -d '{"password": "q1w2e3r4"}' -w "\nHTTP %{http_code}\n"

实测回显：

{"id":"e1e03a1f-dadc-4e6f-8564-88e96a1605e3"}
HTTP 201

授予角色并复核：

curl -sk -b /tmp/wg-cookies.txt -X POST "https://127.0.0.1:8888/@warpgate/admin/api/users/7900f03b-127b-4fef-9800-20ce9c233c69/roles/50e42bf7-09ef-4c23-bbb0-545f478b6595" -d '{}' -w "\nHTTP %{http_code}\n"
curl -sk -b /tmp/wg-cookies.txt "https://127.0.0.1:8888/@warpgate/admin/api/users/7900f03b-127b-4fef-9800-20ce9c233c69/roles"; echo

实测回显：

{"description":"Ops team access","expires_at":null,"granted_at":"2026-10-27T07:31:24.62759692Z","id":"50e42bf7-09ef-4c23-bbb0-545f478b6595","is_active":true,"is_expired":false,"name":"ops-team"}
HTTP 201
[{"description":"Ops team access","expires_at":null,"granted_at":"2026-10-27T07:31:24.62759692Z","id":"50e42bf7-09ef-4c23-bbb0-545f478b6595","is_active":true,"is_expired":false,"name":"ops-team"}]

9.8 经 Warpgate SSH 接入目标

在任意能访问 Warpgate 2222 端口的客户端上，用「Warpgate 用户名:目标名」作为 SSH 登录名直连：

sshpass -p q1w2e3r4 ssh -tt -p 2222 \
  -o StrictHostKeyChecking=no -o UserKnownHostsFile=/root/.ssh/known_hosts_wg \
  appdev:web-01@10.89.56.10 "hostname && id && echo CONNECTED-VIA-WARPGATE"

实测回显：

Warning: Permanently added '[10.89.56.10]:2222' (ED25519) to the list of known hosts.

● You ───── ● Warpgate ┈┈┈─ ○ web-01
● You ───── ● Warpgate ───── ● web-01

target01
uid=0(root) gid=0(root) groups=0(root)
CONNECTED-VIA-WARPGATE
Connection to 10.89.56.10 closed.

解读：第一行灰点拓扑条是 Warpgate 打印的连接进度（You→Warpgate→web-01 逐段点亮），随后命令已在目标机执行——hostname 返回目标机主机名 target01，说明 SSH 流量经 Warpgate 认证后透明转发到 10.89.56.20；密码只输入了 Warpgate 侧的 q1w2e3r4（appdev 的密码），连向目标机的 root 凭证由 Warpgate 代持，用户全程不可见。

9.9 经 Warpgate HTTP 代理访问内网站点

浏览器登录 https://10.89.56.10:8888/ 后在目标列表点击 intranet-portal 即可；脚本化等价形态是带会话 Cookie 访问 /?warpgate-target=<目标名>：

curl -sk -c /tmp/appdev-cookies.txt -X POST -H "Content-Type: application/json" \
  -d '{"username":"appdev","password":"q1w2e3r4"}' \
  -o /dev/null -w "login HTTP %{http_code}\n" https://127.0.0.1:8888/@warpgate/api/auth/login
curl -sk -b /tmp/appdev-cookies.txt "https://127.0.0.1:8888/?warpgate-target=intranet-portal" -D -

实测回显：

login HTTP 201
HTTP/1.1 200 OK
server: nginx/1.18.0 (Ubuntu)
date: Tue, 27 Oct 2026 07:36:31 GMT
accept-ranges: bytes
etag: "6ae05202-22"
last-modified: Tue, 27 Oct 2026 07:25:54 GMT
content-type: text/html; charset=utf-8
strict-transport-security: max-age=31536000
content-length: 34

web-hello-from-target-10.89.56.20

响应头 server: nginx/1.18.0 (Ubuntu) 与正文均来自目标机 10.89.56.20，说明 Warpgate 已按 Cookie 会话把 HTTP 流量反向代理到了授权目标；strict-transport-security 由 Warpgate 注入。未登录直接访问 / 会得到 307 重定向到 /@warpgate 登录页。

9.10 会话录制核验

录制文件按「会话 ID/目标会话 ID」两级目录落盘：

find /var/lib/warpgate -type f | head -20

实测回显（Warpgate 服务器）：

/var/lib/warpgate/tls.key.pem
/var/lib/warpgate/recordings/7aedf409-e886-4142-80c7-0cf380f034bb/c84be108-c78d-49ac-8812-6a44f2b86880/index.ndjson
/var/lib/warpgate/recordings/7aedf409-e886-4142-80c7-0cf380f034bb/c84be108-c78d-49ac-8812-6a44f2b86880/data.ndjson
/var/lib/warpgate/tls.certificate.pem
/var/lib/warpgate/db/db.sqlite3-wal
/var/lib/warpgate/db/db.sqlite3-shm
/var/lib/warpgate/db/db.sqlite3

recordings/ 下即 9.8 节那次 SSH 会话的录制（index.ndjson 为事件索引、data.ndjson 为终端数据流）。管理台 Sessions 页可实时观看与回放；API 侧同样可查：

curl -sk -b /tmp/wg-cookies.txt "https://127.0.0.1:8888/@warpgate/admin/api/sessions"

实测回显（节选）：

{"items":[{"admin_approvals":[],"ended":"2026-10-27T07:31:59.033085397Z","id":"85a4effe-78a5-4534-8bc6-12cfaf7d0ccd","node_hostname":"warpgate","node_id":"26dd8132-9b4c-4d62-9951-95e5e90e0db1","protocol":"SSH","remote_address":"127.0.0.1:56162","started":"2026-10-27T07:31:57.779868166Z","target_sessions":[{"ended":"2026-10-27T07:31:59.03326853Z","id":"7aedf409-e886-4142-80c7-0cf380f034bb","target":{"name":"web-01", ...

protocol: SSH、目标 web-01、录制 ID 与磁盘文件一一对应，审计闭环成立。

十、常见问题与排障实录

Q1：warpgate setup / warpgate recover-access 报 "Please run this command from an interactive terminal." 这两个命令必须交互终端执行（密码输入依赖 TTY），脚本/管道方式实测必现（回显见 5 节排障实录）。无人值守初始化用 unattended-setup；recover-access 改到有 TTY 的控制台运行。

Q2：curl 访问管理台报 curl: (60) SSL certificate problem: self-signed certificate 初始化默认生成自签证书，实测报错原文：

curl: (60) SSL certificate problem: self-signed certificate

处理：测试环境加 -k；正式环境在配置中把 http.certificate/http.key 换成受信 CA 证书后重启服务，或用 --tls-certificate/--tls-key 在初始化时直接注入正式证书。

Q3：GitHub 下载二进制缓慢或失败 本环境实测走 http://192.168.1.62:7897 代理下载成功（4.1 节 ⚠️ 说明）；亦可用国内镜像站点同名附件替代，下载后以 warpgate version 验证。

Q4：服务 active 但端口连不上 按 systemctl status 日志中的 Binding listener 行核对实际监听地址与端口（本机回显见 4.4 节），用 ss -ltnp | grep warpgate 复核；再检查中间防火墙对 8888/2222 等端口的放行。

Q5：SSH 连接目标时报主机密钥确认 ssh.host_key_verification 默认 prompt 会在连接时要求确认；首次初始化阶段用 auto-accept（本文做法），目标密钥稳定后改回 prompt 并在管理台 known-hosts 中固化（详见 4.2 节技术拓展）。

Q6：想换数据库或迁移 配置 database_url 支持 sqlite:、mysql://、postgres:// 三种前缀；存量数据用 warpgate copy-database <TARGET_URL> 整库复制（命令详解见《Warpgate 常用 CLI 命令详解》）。

十一、卸载与清理

systemctl disable --now warpgate.service
rm -f /etc/systemd/system/warpgate.service
systemctl daemon-reload
rm -f /usr/bin/warpgate /etc/warpgate.yaml
rm -rf /var/lib/warpgate

按序停止并摘除开机自启、删除服务单元、二进制、配置与数据目录（含录制与数据库）。若配置了防火墙放行，同步回收对应端口。

十二、参考链接

本专栏：《Warpgate 介绍与选型指南》（定位/架构/选型对比）、后续《Warpgate 配置参数详解》《Warpgate 常用 CLI 命令详解》；
官方 Getting started (binary)：https://warpgate.null.page/getting-started/
systemd 服务安装（官方）：https://warpgate.null.page/installing-as-a-systemd-service/
Releases：https://github.com/warp-tech/warpgate/releases
配置 Schema：https://github.com/warp-tech/warpgate/blob/main/config-schema.json