主题
登录与身份
本页覆盖 login / logout / whoami 三个命令,以及 JWT 与 API Token 的取舍。服务器条目的建立与管理见 安装与服务器管理。
login:登录并保存 token
交互式
省略 -p 时密码以不回显方式输入(golang.org/x/term.ReadPassword);省略 -u 时提示输入用户名(默认 admin):
bash
deploy login -a http://127.0.0.1:10055 -u admin非交互(CI)
powershell
deploy login -a http://127.0.0.1:10055 -u admin -p "$env:DEPLOY_PASSWORD"无 TTY 环境下 -u 与 -p 必须显式给出(或改用 --token),否则报用法错误(退出码 2)。
--token:直接写入 API Token
跳过用户名密码登录,直接落盘一个 API Token 或 JWT(-t 是其短形式):
bash
deploy login -a https://deploy.example.com --token dk_xxxxxxxx写入前会先调 GET /auth/me 校验:返回 401 则不落盘(退出码 3);若是网络类错误无法校验,会给出 stderr 警告但仍然写入(离线预置 token 的场景)。校验成功时顺便补全用户名。
--name:写进哪台服务器
登录结果写入 --name 指定的服务器;不存在则在登录成功后自动创建,并把它设为当前服务器。省略 --name 时写入名为 default 的服务器:
bash
deploy login -a https://prod.example.com -u admin --name prod
deploy --server prod whoami注意一个刻意的设计:全局 --server 不决定 login 的写入目标,它只决定「用哪台已存好的地址/token 发请求」。写入目标只认 --name(缺省 default)。显式传了 --server 却没传 --name 时,CLI 会在 stderr 给出警告,提醒登录结果会写进 default。
| flag | 说明 |
|---|---|
-a, --address URL | 服务端地址(缺省取当前解析出的地址) |
-u, --username USER | 用户名(默认 admin) |
-p, --password PASS | 密码;省略时交互输入且不回显 |
-t, --token TOKEN | 直接写入 API Token / JWT,跳过登录 |
--name NAME | 写入目标服务器(不存在则创建;缺省 default) |
登录成功且账号被标记为必须改密时,会提示去 Web UI 或 /auth/change-password 修改。
logout:登出
bash
deploy logout清空当前服务器的 token,同时尽力调 POST /auth/logout 通知服务端;通知失败不影响本地清理(JWT 无状态)。--json 输出 { server, cleared }。
whoami:确认身份
bash
deploy whoami # 显示用户/昵称/角色/状态/服务器名字/地址/最近登录
deploy whoami --json # { server:<解析出的服务器名字>, address:<URL>, name:<current>, user:{...} }token 失效时返回退出码 3,服务端不可达时返回退出码 4——脚本可以用它做「连通性 + 鉴权」双重探针。使用 --server 临时指定时,JSON 里的 server 是实际使用的服务器,name 仍是配置文件的 current。
JWT 还是 API Token
建议自动化一律使用 API Token(dk_ 前缀),而不是用户名密码换来的 JWT:
| 凭据 | 有效期 | 撤销 | 适用场景 |
|---|---|---|---|
| JWT(login 用户名密码) | 会过期,过期后请求 401(退出码 3) | 随过期失效 | 人工临时操作 |
API Token(dk_ 前缀) | 长期有效 | 服务端可随时撤销 | CI / AI / 无人值守 |
JWT 会过期,无人值守的 CI / AI 用它会在某个时刻突然 401。API Token 在服务端「个人设置 → API Token」创建,长期有效、可随时撤销,创建方式见 凭据与 API Token。认证 header 的格式(Authorization: <裸 token>,无 Bearer 前缀)见 认证与通用约定。
login 的输出与退出码
用户名密码登录成功的 --json 输出(token 打码):
json
{
"address": "http://127.0.0.1:10055",
"server": "default",
"name": "default",
"username": "admin",
"role": "admin",
"token": "eyJh******cdef",
"expiresAt": 1767225600
}--token 直写成功时输出 { address, server, name, username, token }(无 role/expiresAt)。人类输出会额外提示 token 保存路径与 JWT 的到期时间。
| 场景 | 退出码 |
|---|---|
| 登录成功 / token 校验通过并落盘 | 0 |
非交互缺 -u/-p、地址为空、--name 非法 | 2 |
| 用户名密码错误、token 无效或过期(401) | 3 |
| 服务端不可达、未返回 token | 4 |
CI 里的零配置用法
CI 可以完全不落配置文件:直接用环境变量提供地址与 token(优先级见 安装与服务器管理):
bash
export DEPLOY_ADDRESS=https://deploy.example.com
export DEPLOY_TOKEN=dk_xxxxxxxx
deploy whoami --json # 探针:退出码 3=token 失效、4=不可达
deploy run my-app --wait --json # 部署并等待终态需要多台服务器时再引入配置文件与 --server;token 请通过 CI 的密钥管理注入,不要写进仓库。
token 打码约定
server list、server get、whoami、config get(全量)、login 结果等输出里 token 一律打码(保留前 4 位与后 4 位,中间以 6 个星号代替;空 token 显示 (not set))。唯一的例外是 deploy config get token:它输出明文,专供脚本取值(见 输出约定与退出码)。--verbose 的调试输出同样只打印打码后的 token。