Coder 2.37.7 常用 CLI 与运维命令详解

目标：把日常运维要用的 coder 命令按场景串起来——认证、服务托管、用户令牌、模板、工作区、组织许可、排障。除标注「官方用法」外，本文命令与回显均来自 2026-10-27 至 2026-10-28 的实测环境（Coder v2.37.7+b40ba6e / Ubuntu 22.04 / PostgreSQL 16.15）。安装见《Ubuntu 22.04 安装 Coder 2.37.7 指南》，参数含义见《Coder 2.37.7 配置参数详解》。

一、环境信息

Coder 版本：Coder v2.37.7+b40ba6e Mon Oct 26 23:31:01 UTC 2026
CLI 位置：/opt/coder/coder，符号链接 /usr/local/bin/coder
服务地址：http://192.168.1.71:3000
管理员：admin / admin@coder.local
全局配置目录：/root/.config/coderv2（--global-config / CODER_CONFIG_DIR）
子命令数量：49 个（coder --help 实测）
内置 provisioner：3 个，版本 v2.37.7+b40ba6e，状态 idle

二、工具概览

coder 既是服务端二进制，也是完整的运维 CLI。把 49 个子命令按用途归类：

类别	子命令
服务端	`server`（含 `create-admin-user`、`dbcrypt`、`postgres-builtin-*`）
认证	`login`、`logout`、`whoami`、`tokens`、`reset-password`
用户与组织	`users`、`groups`、`organizations`、`licenses`、`features`
模板	`templates`（`init/list/push/pull/delete/versions/archive/presets/edit`）
编排	`provisioner`（`list/start/jobs/keys`）
工作区	`create`、`list`、`show`、`start`、`stop`、`restart`、`update`、`delete`、`rename`、`schedule`、`autoupdate`
接入	`ssh`、`port-forward`、`open`、`config-ssh`、`publickey`
辅助	`dotfiles`、`favorite`、`unfavorite`、`stat`、`state`、`logs`、`ping`、`speedtest`、`netcheck`
排障	`support bundle`
其他	`notifications`、`oauth2-provider`、`ai-gateway`、`external-auth`、`external-workspaces`、`prebuilds`、`secret`、`completion`、`version`

2.1 全局参数

全局参数对所有子命令生效，常用项：

参数	环境变量	说明
`--url`	`CODER_URL`	目标部署地址
`--token`	`CODER_SESSION_TOKEN`	会话令牌，安全场景优先用环境变量
`--global-config`	`CODER_CONFIG_DIR`	配置目录，默认 `/root/.config/coderv2`
`--use-keyring`	`CODER_USE_KEYRING`	默认 true，用系统密钥环存令牌
`--verbose` / `-v`	`CODER_VERBOSE`	输出调试信息
`--no-version-warning`	`CODER_NO_VERSION_WARNING`	抑制客户端/服务端版本不一致告警
`--debug-options`	无	打印所有参数及来源后退出

三、认证与前置

3.1 登录

coder login http://192.168.1.71:3000

交互式输入邮箱与密码，成功后令牌写入系统密钥环（无密钥环时写入配置目录）。CI/脚本场景改用令牌：

export CODER_URL=http://192.168.1.71:3000
export CODER_SESSION_TOKEN=<令牌>
coder whoami

3.2 确认身份

coder whoami

输出会同时给出服务地址与当前用户名。脚本里建议只取用户名，避免地址变化影响判断。

3.3 登出

coder logout

该命令会二次确认（Are you sure you want to log out? (yes/no)），非交互环境会直接报 error: EOF。

四、服务进程与 systemd 运维

4.1 常用命令

systemctl start coder
systemctl stop coder
systemctl restart coder
systemctl is-active coder
systemctl status coder --no-pager
systemctl enable coder

实测 is-active 返回 active；status 显示 Loaded: loaded (/etc/systemd/system/coder.service; enabled)、Active: active (running)、Memory: 773.4M、CPU: 5.838s。

4.2 日志

journalctl -u coder -f
journalctl -u coder --since "30 min ago"
journalctl -u coder -p err

若在 env 文件中设置了 CODER_LOGGING_HUMAN=/dev/stdout，日志会进入 journald；否则默认写 /dev/stderr，同样能被 journald 捕获。JSON 日志则需另行采集。

4.3 健康检查

curl -s http://127.0.0.1:3000/healthz
# OK

ss -ltnp | grep 3000
# LISTEN 0  4096  *:3000  *:*  users:(("coder",pid=8362,fd=3))

/healthz 适合接入负载均衡与监控；/api/v2/buildinfo 可查看版本、agent API 版本与 provisioner API 版本（其中包含部署 ID 等信息，对外暴露前注意脱敏）。

4.4 优雅重启

systemctl restart coder
journalctl -u coder -n 20 --no-pager

单元中 KillSignal=SIGINT + TimeoutStopSec=90 会让 Coder 先等待未完成的 provisioner 任务收尾。实测重启日志会依次出现 coderd: gracefully shutdown、provisionerd-...: gracefully shutdown、pubsub is closing 等行，随后新进程打印 Started HTTP listener at http://0.0.0.0:3000。

4.5 创建管理员（数据库直连）

sudo -u coder sh -c '. /etc/coder.d/coder.env; /opt/coder/coder server create-admin-user \
  --username admin --email admin@coder.local --password "q1w2e3r4"'

该子命令绕过 Web 注册，直接把用户写入数据库并加入所有组织，是部署后第一次可登录的前提。

五、用户与令牌

5.1 用户列表与详情

coder users list

实测回显：

USERNAME  EMAIL              CREATED AT            STATUS
admin     admin@coder.local  2026-10-27T17:23:50Z  active
dev01     dev01@coder.local  2026-10-27T17:25:03Z  dormant

新建用户默认是 dormant（休眠）状态，需要激活后才能正常使用。

coder users show dev01

ID:             631512f4-47e3-4eca-a79c-7443dcd24c86
Username:       dev01
Full name:      Dev User
Email:          dev01@coder.local
Status:         dormant
Roles:          (none)
Organizations:  coder

5.2 新建用户

coder users create \
  --username dev01 \
  --email dev01@coder.local \
  --full-name "Dev User" \
  --password 'Q1w2e3r4!'

实测输出的关键行：

A new user has been created!
Your email is: dev01@coder.local
Your password is: Q1w2e3r4!

创建成功后状态仍是 dormant，需要 coder users activate dev01 并确认。

5.3 激活、暂停、删除

coder users activate dev01
coder users suspend dev01
coder users delete dev01

三个命令都是交互式确认：

> Are you sure you want to activate this user? (yes/no)
User dev01 has been activated!

非交互执行会得到 error: EOF。删除用户不支持 --yes（实测传 --yes 会报 unknown flag）。

5.4 修改角色

coder users edit-roles dev01 owner
coder users edit-roles dev01 member

角色变更影响工作区与模板的可见范围，生产环境应走审批。

5.5 令牌

coder tokens create --name lab-token
coder tokens list
coder tokens delete <令牌ID或值>

实测 tokens create 只输出一次令牌值，必须当场保存：

9JJGktKv0j-BxmTixO242PJHyEZtAZ0os

tokens list 只显示前 10 位、作用域、允许列表与过期时间：

ID          NAME       SCOPES     ALLOW LIST  LAST USED             EXPIRES AT            CREATED AT
9JJGktKv0j  lab-token  coder:all  *:*         1970-01-01T00:00:00Z  2026-10-28T17:25:03Z  2026-10-27T17:25:03Z

默认有效期为 168 小时（7 天），由服务端 --default-token-lifetime 控制。

5.6 重置密码（官方用法）

coder reset-password --postgres-url "postgres://coder:<密码>@127.0.0.1:5432/coder?sslmode=disable" <用户名>

该命令直接连数据库改密码，适合管理员被锁在外的情况；执行前确认连接串与备份。

六、模板与 provisioner

6.1 初始化模板

coder templates init

交互式选择官方示例模板，生成到当前目录。模板是标准 Terraform 工程，必须包含 coder Provider 与至少一个 coder_agent 资源。

6.2 推送模板

最小可推送模板（仅注入 agent，不创建计算资源，适合验证流程）：

terraform {
  required_providers {
    coder = {
      source = "coder/coder"
    }
  }
}

data "coder_workspace" "me" {}

resource "coder_agent" "main" {
  os   = "linux"
  arch = "amd64"
}

cd /opt/templates/lab-template
coder templates push lab-template

实测推送后：

coder templates list

NAME          ORGANIZATION NAME  LAST UPDATED      USED BY
lab-template  coder              October 27, 2026  0 active developers

6.3 模板版本与删除

coder templates versions list lab-template
coder templates pull lab-template
coder templates archive lab-template
coder templates delete lab-template

删除实测回显：Deleted template lab-template at Oct 27 17:31:05。删除模板不会自动删除基于它创建的工作区，需先处理工作区。

6.4 provisioner

coder provisioner list

CREATED AT            LAST SEEN AT          KEY NAME  NAME            VERSION          STATUS  TAGS
2026-10-27T17:23:21Z  ...                   built-in  coder-node01-0  v2.37.7+b40ba6e  idle    map[owner: scope:organization]
2026-10-27T17:23:21Z  ...                   built-in  coder-node01-1  v2.37.7+b40ba6e  idle    map[owner: scope:organization]
2026-10-27T17:23:21Z  ...                   built-in  coder-node01-2  v2.37.7+b40ba6e  idle    map[owner: scope:organization]

三个内置守护进程对应 --provisioner-daemons 的默认值 3。任务长期排队时可增大该值，或按官方用法启动外部守护进程：

coder provisioner start --psk <预共享密钥> --tag scope=organization
coder provisioner jobs list
coder provisioner keys list

外部守护进程属于企业版能力 external_provisioner_daemons，社区版不可用。

七、工作区生命周期

7.1 创建

coder create demo-ws --template lab-template

实测输出（节选）：

=== ✔ Initializing Terraform Directory [2211ms]
==> ⧗ Planning Infrastructure
2026-10-27 17:27:18.756Z coder_agent.main: Plan to create
2026-10-27 17:27:18.756Z Plan: 1 to add, 0 to change, 0 to destroy.
=== ✔ Planning Infrastructure [137ms]
==> ⧗ Starting workspace
2026-10-27 17:27:18.857Z Terraform 1.16.7
2026-10-27 17:27:18.913Z coder_agent.main: Creation complete after 0s
=== ✔ Starting workspace [270ms]

The demo-ws workspace has been created at Oct 27 17:27:19!

首次创建会下载 Terraform 与 Provider，耗时取决于网络；后续走缓存明显更快。

7.2 列表与详情

coder list

WORKSPACE        TEMPLATE      STATUS   HEALTHY  LAST BUILT  CURRENT VERSION  OUTDATED
admin/demo-ws    lab-template  Started  true     <1m         young_beahan12   false

coder show demo-ws

┌───────────────────────────────────────────┐
│ admin/demo-ws (running since 10s) lab-tem │
│ plate:young_beahan12                      │
├───────────────────────────────────────────┤
│ RESOURCE  STATUS  HEALTH  VERSION  ACCESS │
├───────────────────────────────────────────┤
└───────────────────────────────────────────┘

coder list --all 可查看所有用户的工作区。

7.3 启停与重启

coder stop demo-ws
coder start demo-ws
coder restart demo-ws

停止实测：

2026-10-27 17:27:28.830Z Apply complete! Resources: 0 added, 0 changed, 0 destroyed.
=== ✔ Stopping workspace [289ms]

The demo-ws workspace has been stopped at Oct 27 17:27:29!

停止后列表状态变为 Stopped，HEALTHY 列为空。

7.4 更新与删除

coder update demo-ws
coder delete demo-ws

删除实测：

2026-10-27 17:31:04.785Z coder_agent.main: Destroying...
2026-10-27 17:31:04.786Z coder_agent.main: Destruction complete after 0s
=== ✔ Destroying workspace [250ms]

admin/demo-ws has been deleted at Oct 27 17:31:04!

coder delete 会真正执行 terraform destroy，工作区内的数据是否保留取决于模板的存储设计。

7.5 接入工作区

coder ssh demo-ws
coder ssh demo-ws -- ls -al
coder port-forward demo-ws --tcp 3000:3000
coder open demo-ws
coder config-ssh
coder publickey

config-ssh 会把工作区写入 ~/.ssh/config，之后可直接 ssh demo-ws.coder；publickey 输出用于 Git 操作的公钥。

7.6 定时与自动更新

coder schedule start demo-ws --at 09:00 --timezone Asia/Shanghai
coder schedule stop demo-ws --at 19:00 --timezone Asia/Shanghai
coder autoupdate demo-ws always

定时策略可降低闲置成本；模板频繁更新时 autoupdate 让工作区自动跟进。

八、组织、许可与特性

8.1 组织

coder organizations list

NAME   DISPLAY NAME  ID                                    DEFAULT
coder  Coder         f9391c36-96a8-4971-8293-f17fa02886b9  true

8.2 许可

coder licenses list
# No licenses found.

社区版无需许可；导入许可证后企业特性才会解锁。

8.3 特性

coder features list

实测输出 28 项，社区版全部为 not_entitled，例如：

NAME                          ENTITLEMENT   ENABLED  LIMIT  ACTUAL
access_control                not_entitled  false    <nil>  <nil>
audit_log                     not_entitled  false    <nil>  <nil>
external_provisioner_daemons  not_entitled  false    <nil>  <nil>
high_availability             not_entitled  false    <nil>  <nil>
multiple_organizations        not_entitled  false    <nil>  <nil>
scim                          not_entitled  false    <nil>  <nil>
template_rbac                 not_entitled  false    <nil>  <nil>
user_limit                    not_entitled  false    <nil>  0
workspace_proxy               not_entitled  false    <nil>  <nil>

8.4 分组

coder groups list

社区版实测报错：

error: Trace=[get groups: ]
Template RBAC is a Premium feature. Contact sales!

需要分组与模板级权限时，必须引入 Premium/Enterprise 授权。

九、排障命令

9.1 support bundle（官方用法）

coder support bundle

采集部署信息、工作区连接诊断与日志，生成压缩包供支持团队分析。命令会读取 ~/.config/coderv2 中的登录态，建议用管理员令牌执行；产物含环境信息，外发前先脱敏。

9.2 工作区日志

coder logs demo-ws
coder logs demo-ws --follow

查看 agent 与启动脚本输出，工作区启动失败时优先看这里。

9.3 网络诊断

coder ping demo-ws
coder netcheck
coder speedtest demo-ws

ping：测量到工作区的延迟与连接类型（直连/中继）；
netcheck：打印 DERP 与 STUN 的探测结果，跨 NAT 不通时用它定位；
speedtest：上下行带宽测试，排查大文件同步慢的问题。

9.4 资源与状态

coder stat cpu
coder stat mem
coder state pull demo-ws

stat 读取当前工作区资源占用；state 用于手工修复 Terraform 状态损坏的工作区，操作前务必备份。

9.5 常见错误回显

# 数据库密码错误（重试 11 次后退出）
error: connect to postgres: connect to postgres: unable to connect after 11 tries; last error: pq: password authentication failed for user "coder"

# 端口被占用
error: configure http(s): listen tcp 127.0.0.1:3000: bind: address already in use

# access URL 缺少 scheme
error: access-url must include a scheme (e.g. 'http://' or 'https://)

十、升级、备份与回滚

10.1 备份

升级前先备份数据库：

sudo -u postgres pg_dump -Fc coder > /var/backups/coder-$(date +%F-%H%M).dump

同时备份 /etc/coder.d/（env 与 YAML）与 /var/cache/coder 中的必要缓存。

10.2 升级

# standalone
sh /root/install.sh --stable --version <新版本>
systemctl restart coder

# deb
curl -fL -o /tmp/coder_<新版本>_linux_amd64.deb \
  https://github.com/coder/coder/releases/download/v<新版本>/coder_<新版本>_linux_amd64.deb
dpkg -i /tmp/coder_<新版本>_linux_amd64.deb
systemctl restart coder

控制面启动时自动执行数据库迁移。迁移通常不可逆，回滚需要「旧二进制 + 升级前数据库备份」一起恢复。

10.3 回滚

systemctl stop coder
sudo -u postgres pg_restore -d coder --clean --if-exists /var/backups/coder-<时间>.dump
sh /root/install.sh --version <旧版本>
systemctl start coder

十一、FAQ

11.1 非交互执行确认类命令报 EOF

users suspend/activate/delete、logout 都有 (yes/no) 确认。脚本中可用管道输入：

echo yes | coder users activate dev01

或改用 API/令牌方式操作，避免依赖 TTY。

11.2 `coder users delete --yes` 报未知参数

实测 2.37.7 的 users delete 没有 --yes：

parsing flags ([users delete dev01 --yes]) for "coder users delete": unknown flag: --yes

改用交互确认或管道输入。

11.3 新建用户无法登录

先看状态。新建用户默认 dormant，需 coder users activate。若密码是小写组合，可能被密码策略拒绝；普通用户建议使用 Q1w2e3r4! 这类「大写+小写+数字+符号」口令。

11.4 `groups list` 报 Premium

分组与模板 RBAC 属于付费能力，社区版无法使用。评估需求时以 coder features list 为准。

11.5 `features list` 全是 not_entitled

社区版没有许可证，所有企业特性均未授权，属正常现象；user_limit 的 ACTUAL 为 0 也不代表不能用，只是没有配额限制。

11.6 `provisioner list` 只有 built-in

默认 3 个内置守护进程已够中小规模使用。需要隔离或扩容时启动外部守护进程，但那需要企业授权与 PSK 配置。

11.7 令牌丢了怎么办

tokens create 只在创建时回显一次。丢失后无法找回，只能 tokens delete 旧令牌再新建。生产环境把令牌存入密钥管理系统，不要写进脚本。

11.8 工作区卡在 queued

先看 coder provisioner list 是否全部 idle、coder provisioner jobs list 是否有失败任务，再看 journalctl -u coder 中 provisioner 的报错。常见原因是 Terraform Provider 下载失败或模板凭据过期。

11.9 客户端与服务端版本不一致

CLI 会提示版本不一致。测试环境可用 --no-version-warning 抑制；生产应保持 CLI 与服务端同版本，避免 API 行为差异。

十二、参考链接

CLI 参考：https://coder.com/docs/reference/cli
工作区操作：https://coder.com/docs/user-guides/workspace-access
模板开发：https://coder.com/docs/templates
用户管理：https://coder.com/docs/admin/users
排障与支持：https://coder.com/docs/admin/troubleshooting
GitHub Releases：https://github.com/coder/coder/releases
站内：《Coder 介绍与选型指南》、《Ubuntu 22.04 安装 Coder 2.37.7 指南》、《Coder 2.37.7 配置参数详解》

Coder 2.37.7 常用 CLI 与运维命令详解

Coder 2.37.7 常用 CLI 与运维命令详解

一、环境信息

二、工具概览

2.1 全局参数

三、认证与前置

3.1 登录

3.2 确认身份

3.3 登出

四、服务进程与 systemd 运维

4.1 常用命令

4.2 日志

4.3 健康检查

4.4 优雅重启

4.5 创建管理员（数据库直连）

五、用户与令牌

5.1 用户列表与详情

5.2 新建用户

5.3 激活、暂停、删除

5.4 修改角色

5.5 令牌

5.6 重置密码（官方用法）

六、模板与 provisioner

6.1 初始化模板

6.2 推送模板

6.3 模板版本与删除

6.4 provisioner

七、工作区生命周期

7.1 创建

7.2 列表与详情

7.3 启停与重启

7.4 更新与删除

7.5 接入工作区

7.6 定时与自动更新

八、组织、许可与特性

8.1 组织

8.2 许可

8.3 特性

8.4 分组

九、排障命令

9.1 support bundle（官方用法）

9.2 工作区日志

9.3 网络诊断

9.4 资源与状态

9.5 常见错误回显

十、升级、备份与回滚

10.1 备份

10.2 升级

10.3 回滚

十一、FAQ

11.1 非交互执行确认类命令报 EOF

11.2 coder users delete --yes 报未知参数

11.3 新建用户无法登录

11.4 groups list 报 Premium

11.5 features list 全是 not_entitled

11.6 provisioner list 只有 built-in

11.7 令牌丢了怎么办

11.8 工作区卡在 queued

11.9 客户端与服务端版本不一致

十二、参考链接

11.2 `coder users delete --yes` 报未知参数

11.4 `groups list` 报 Premium

11.5 `features list` 全是 not_entitled

11.6 `provisioner list` 只有 built-in