Skip to content

登录与身份 ​

本页覆盖 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
服务端不可达、未返回 token4

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。