主题
安装与服务器管理
本页覆盖 deploy 二进制的构建与安装、本地配置文件,以及 server 命令组的全部用法。登录与 token 的细节见 登录与身份。
安装
从源码构建
需要 Go 1.24+。main 包位于 cmd/deploy/,因此 go build 必须写 ./cmd/deploy:
powershell
cd deploy-cli
go build -o deploy.exe ./cmd/deploy # Windows
go build -o deploy ./cmd/deploy # Linux / macOS也可以直接装进 GOBIN(未设置时是 $GOPATH/bin):
powershell
go install ./cmd/deploygo install 按导入路径最后一段命名,所以产出的命令名就是 deploy(早期 main 在模块根时产出的是 deploy-cli)。
带版本信息构建(deploy version 会显示,见 07):
powershell
go build -ldflags "-s -w `
-X deploy-cli/internal/version.Version=0.1.0 `
-X deploy-cli/internal/version.Commit=$(git rev-parse --short HEAD) `
-X deploy-cli/internal/version.BuildTime=$(Get-Date -Format o)" -o deploy.exe ./cmd/deploy交叉编译
powershell
$env:GOOS='linux'; $env:GOARCH='amd64'; go build -o deploy-linux-amd64 ./cmd/deploy
$env:GOOS='linux'; $env:GOARCH='arm64'; go build -o deploy-linux-arm64 ./cmd/deploy
$env:GOOS='darwin'; $env:GOARCH='arm64'; go build -o deploy-darwin-arm64 ./cmd/deploy
$env:GOOS='windows'; $env:GOARCH='amd64' # 记得还原把二进制放到 PATH
powershell
Move-Item deploy.exe "$env:USERPROFILE\bin\deploy.exe" # 确保该目录已在 PATH 中
# 或者直接装到 GOBIN(未设置时是 $GOPATH/bin)
go install ./cmd/deploy快速开始中的安装步骤另见 安装 CLI。
配置文件
配置文件为 ~/.deploy/config.yaml(Windows:%USERPROFILE%\.deploy\config.yaml)。保存时目录权限 0700、文件权限 0600(Windows 上权限位是尽力而为)。可用环境变量 DEPLOY_CONFIG 指定其它路径。
contexts 下的键就是服务器的名字:部署/运维时用 --server <名字> 指定操作哪一台,server update <旧名> --name <新名> 改的也是它。没有独立的显示名标签:
yaml
current: "97"
contexts:
"97":
address: http://192.168.31.97:10055
token: dk_xxxxxxxx
user: admin
prod:
address: https://deploy.example.com
token: dk_xxxxxxxx
user: adminserver 命令组
add:新增服务器
推荐非交互一条命令建立(并默认设为当前服务器);同名会被更新,不会重复添加:
bash
deploy server add 97 -a http://192.168.31.97:10055 -t dk_xxxxxxxx -u admin
deploy server add prod -a https://deploy.example.com -t dk_xxxxxxxx --no-set-current| flag | 说明 |
|---|---|
-a, --address URL | 服务端地址(必填) |
-t, --token TOKEN | API Token 或 JWT;交互环境下省略会提示输入(可留空) |
-u, --user USER | 用户名(仅记录,供 whoami 显示) |
--comment TEXT | 备注,如 test-box |
--no-set-current | 不把它设为默认服务器 |
只填地址不填 token 是允许的(之后可 deploy login -a <地址> --name <名字> 补,或 deploy server update <名字> -t <token>),但命令会明确提示还没有 token。
名字(位置参数,也是配置里的键)允许中文与点/短横线,最长 64 字符,但不能含空格、冒号、斜杠——否则 --server 传参要靠引号、并与 URL scheme 混淆。
list / get / current:查看
bash
deploy server list # 表格:* 标记当前,NAME=名字(即配置里的键),token 打码
deploy server list --json # { current, path, servers:[{key,name,address,user,comment,token,active}] }
deploy server get 97 # 单个服务器的名字/地址/用户/备注/是否当前
deploy server get 97 --json # { key, name, address, user, comment, token, active }
deploy server current # 只打印当前服务器名字(便于脚本取值)
deploy server current --json # { current, path, name, address, user, token, comment }key 与 name 同值(键就是名字),两个字段都保留是为了兼容已有 JSON 消费方。add / update / get 的 JSON 同形,URL 字段名是 address。
use:切换默认服务器
bash
deploy server use 97不改默认服务器、临时指定某一台(推荐脚本/CI 用这种,无状态):
bash
deploy --server prod run my-app --wait --jsonupdate:只改显式字段
bash
deploy server update 97 -t dk_xxxxxxxx # 只改 token,其余字段保持
deploy server update 97 -a http://10.0.0.5:10055 # 只改地址
deploy server update 97 --name prod # 改名:键与 current 一起变成 prod
deploy server update 97 --comment "测试机"update只改显式传了的字段:不传-t就不会动 token,避免「只想换地址」却把 token 清掉。显式传空串(如--user "")才是清空该字段。--name <新名>就是改名(改键):地址/token/用户名/备注整条搬过去,current跟着走。新名已存在、为空或含空格/冒号/斜杠时报用法错误(退出码 2),不会静默覆盖。- 至少要传一个字段(
-a/-t/-u/--name/--comment),否则退出码 2。
remove:删除
bash
deploy server remove prod # 交互环境下要求输入 yes 确认
deploy server remove prod --yes # 非交互必须 --yes地址与 token 的优先级
从高到低:
| 顺序 | 来源 |
|---|---|
| 1 | 命令行 flag:-a/--address / --token / --server(--server 选配置文件里的某个服务器) |
| 2 | 环境变量:DEPLOY_ADDRESS / DEPLOY_TOKEN(CI 里可以完全不用配置文件;DEPLOY_SERVER 是地址的历史名,仍兼容但优先级低于 DEPLOY_ADDRESS) |
| 3 | 配置文件:--server 指定的服务器,否则 current 指向的服务器 |
| 4 | 默认值:http://127.0.0.1:10055(token 无默认值,为空即视为未登录) |
--server 点名的服务器不存在时不静默回退,而是返回退出码 2 并提示 deploy server list。--verbose 会在 stderr 打印每一项的实际来源(flag / env / config / default),便于排查。
全局 flag
所有子命令都接受以下持久 flag:
| flag | 说明 |
|---|---|
--server <名字> | 使用配置文件中指定名字的服务器(优先于 current) |
-a, --address URL | 覆盖服务端地址。地址覆盖只认 -a/--address;旧的 --server 地址别名已删除 |
--token TOKEN | 覆盖 token(JWT 或 dk_ 开头的 API Token) |
--json | stdout 只输出机器可读 JSON / JSONL,人类提示一律走 stderr |
--no-color | 禁用彩色;非 TTY 或 NO_COLOR=1 时自动禁用 |
--verbose | 调试点(HTTP 请求、重连、配置来源)输出到 stderr |