Ubuntu 22.04 安装 Coder 2.37.7 指南

目标：在 Ubuntu 22.04 服务器上从零搭起 Coder 2.37.7 控制面，覆盖官方脚本、离线压缩包 + 自建 systemd、deb 包三种方案。除特别标注外，本文命令与回显均来自 2026-10-27 至 2026-10-28 的实测环境；产品背景见《Coder 介绍与选型指南》。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（jammy），x86_64
硬件：6 vCPU / 18GiB 内存 / 295GB 磁盘
Coder 版本：v2.37.7（commit b40ba6e，构建时间 2026-10-26 23:31:01 UTC）
数据库：PostgreSQL 16.15，来自 PGDG 的 jammy-pgdg 源，与本机控制面同机部署
服务用户：coder（uid 999，安装 deb 包时由包管理器自动创建）
访问地址：http://192.168.1.71:3000（服务监听 0.0.0.0:3000）
演示管理员：admin / q1w2e3r4（仅用于本文演示，生产环境务必替换）

实测环境的文件布局：

路径	用途
`/opt/coder/coder`	standalone 方案的二进制位置（方案 B）
`/usr/local/bin/coder`	standalone 安装后的 CLI 符号链接/副本（方案 A）
`/usr/bin/coder`	deb 包安装的二进制（方案 C）
`/etc/coder.d/coder.env`	环境变量文件，systemd 的 `EnvironmentFile`
`/etc/coder.d/coder.yaml`	可选的 YAML 配置文件（实验特性，见配置篇）
`/etc/systemd/system/coder.service`	方案 B 自建单元
`/lib/systemd/system/coder.service`	deb 包自带单元

二、前置条件

2.1 系统与资源

官方快速开始建议至少 2 CPU / 4GB 内存。控制面本身开销不大，但模板执行 Terraform、并行创建工作区时会明显吃 CPU 与内存，实测 6 vCPU / 18GiB 的机器可从容运行 3 个内置 provisioner 守护进程。

# 确认系统版本
grep PRETTY_NAME /etc/os-release
# PRETTY_NAME="Ubuntu 22.04.5 LTS"

# 基础工具
apt-get update
apt-get install -y curl ca-certificates gnupg lsb-release iproute2 jq

2.2 安装 PostgreSQL 16

Ubuntu 22.04 官方源自带的是 PostgreSQL 14。Coder 官方要求 13 及以上，本文选择 16。通过 PGDG 官方仓库安装：

# 添加 PGDG 源（官方脚本会自动写入 key 与 sources.list）
curl -fsSL https://apt.postgresql.org/pub/repos/apt/apt.postgresql.org.sh -o /tmp/apt.postgresql.org.sh
bash /tmp/apt.postgresql.org.sh -y

apt-get update
apt-get install -y postgresql-16

# 验证
psql --version
# psql (PostgreSQL) 16.15 (Ubuntu 16.15-1.pgdg22.04+1)

安装完成后 PostgreSQL 默认只监听 127.0.0.1:5432，对同机部署的控制面已经足够：

pg_isready
# /var/run/postgresql:5432 - accepting connections

2.3 创建数据库与账号

sudo -u postgres psql -v ON_ERROR_STOP=1 <<'SQL'
CREATE ROLE coder LOGIN PASSWORD 'q1w2e3r4';
CREATE DATABASE coder OWNER coder;
SQL

# 用密码方式验证连接（对应后续连接串中的 127.0.0.1）
PGPASSWORD=q1w2e3r4 psql -h 127.0.0.1 -U coder -d coder -c 'select current_database(), current_user;'
#  coder | coder

⚠️ 注意：连接串中的密码若包含 @ : / ? # 等特殊字符，必须做 URL 编码，否则 Coder 解析连接串会失败。

2.4 端口与目录

# 3000 为 HTTP 端口，3443 为可选 TLS 端口，2112 为 Prometheus 指标端口
ss -ltn | grep -E ':(3000|3443|2112)\b' || echo "端口空闲"

2.5 访问地址规划

--access-url 必须填写浏览器与工作区实际可达的地址，且必须带 scheme。本文实测使用 http://192.168.1.71:3000。生产环境建议使用域名 + HTTPS，并由反向代理终止 TLS。

三、版本选型

Coder 提供两条发布通道：

通道	版本（2026-10-28 实查）	特点	适用
stable	v2.37.7	官方标记 Stable，发布说明注明自 2026-10-27 起稳定	生产环境
mainline	v2.38.3	功能更新更快，稳定性承诺弱	预研、尝鲜

官方 install.sh 的版本相关参数：

参数	含义
默认	安装最新 mainline
`--stable`	安装最新 stable
`--version X.X.X`	安装指定版本，如 `--version 2.37.7`
`--method detect`	自动识别系统包管理器（deb/rpm 等），无法匹配时回退 standalone
`--method standalone`	直接下载压缩包解压到 `/usr/local/bin`
`--prefix <dir>`	standalone 安装前缀，默认 `/usr/local`
`--dry-run`	只打印将执行的命令，不实际安装
`--with-terraform`	同时安装 Terraform 1.16.7 二进制

生产环境建议固定版本，避免自动跟随最新版：--stable --version 2.37.7。

四、方案 A：官方 install.sh 一键安装

4.1 预检（dry-run）

curl -fsSL https://coder.com/install.sh -o /root/install.sh
sh /root/install.sh --dry-run --stable --version 2.37.7

实测回显（节选）：

Ubuntu 22.04.5 LTS
Running with --dry-run; the following are the commands that would be run if this were a real installation:

Installing v2.37.7 of the amd64 release from GitHub.

+ mkdir -p ~/.cache/coder
+ curl -#fL -o ~/.cache/coder/coder_2.37.7_linux_amd64.tar.gz.incomplete -C - https://github.com/coder/coder/releases/download/v2.37.7/coder_2.37.7_linux_amd64.tar.gz
+ mkdir -p /usr/local
+ tar -C ~/.cache/coder/tmp -xzf ~/.cache/coder/coder_2.37.7_linux_amd64.tar.gz
+ mkdir -p /usr/local/bin
+ cp ~/.cache/coder/tmp/coder /usr/local/bin/coder
Dry-run complete.

脚本会缓存下载产物到 ~/.cache/coder，并使用 .incomplete 临时文件做断点续传，网络抖动可直接重跑。

4.2 实际安装

sh /root/install.sh --stable --version 2.37.7

实测回显：

The Coder binary has been placed in the following location:

  /usr/local/bin/coder

To run a Coder server:

  $ coder server

To connect to a Coder deployment:

  $ coder login <deployment url>

4.3 验证

/usr/local/bin/coder version

实测回显：

Coder v2.37.7+b40ba6e Mon Oct 26 23:31:01 UTC 2026
https://github.com/coder/coder/commit/b40ba6eef4905d73176189278186e6f76dd25afe

Full build of Coder, supports the server subcommand.

4.4 说明

该方案只装二进制，不创建服务用户、不写 systemd 单元、不生成 /etc/coder.d，需要自行托管（见方案 B 的 systemd 部分）；
在 Ubuntu 上 --method detect 也可能回退到 standalone（本次实测即如此），若必须使用 deb 包请显式走方案 C；
升级只需重新执行脚本并指定新版本，旧的二进制会被覆盖；数据库迁移在服务启动时自动执行。

五、方案 B：standalone 压缩包 + 自建 systemd

适合离线环境或需要完全掌控安装布局的场景。

5.1 下载与解压

curl -fL -o /tmp/coder_2.37.7_linux_amd64.tar.gz \
  https://github.com/coder/coder/releases/download/v2.37.7/coder_2.37.7_linux_amd64.tar.gz

mkdir -p /opt/coder
tar -xzf /tmp/coder_2.37.7_linux_amd64.tar.gz -C /tmp
install -m 0755 /tmp/coder /opt/coder/coder
ln -sf /opt/coder/coder /usr/local/bin/coder

/opt/coder/coder version

5.2 服务用户与目录

useradd --system --home-dir /var/lib/coder --create-home --shell /usr/sbin/nologin coder
install -d -o coder -g coder -m 0750 /var/lib/coder /var/cache/coder
install -d -m 0750 /etc/coder.d

5.3 环境变量文件

cat > /etc/coder.d/coder.env <<'EOF'
CODER_HTTP_ADDRESS=0.0.0.0:3000
CODER_ACCESS_URL=http://192.168.1.71:3000
CODER_PG_CONNECTION_URL=postgres://coder:q1w2e3r4@127.0.0.1:5432/coder?sslmode=disable
CODER_LOGGING_HUMAN=/dev/stdout
CODER_CACHE_DIRECTORY=/var/cache/coder
EOF

chown root:coder /etc/coder.d/coder.env
chmod 0640 /etc/coder.d/coder.env

5.4 systemd 单元

[Unit]
Description=Coder control plane
Documentation=https://coder.com/docs
Requires=network-online.target
After=network-online.target
ConditionFileNotEmpty=/etc/coder.d/coder.env
StartLimitIntervalSec=10
StartLimitBurst=3

[Service]
Type=notify
EnvironmentFile=/etc/coder.d/coder.env
User=coder
Group=coder
ProtectSystem=full
PrivateTmp=yes
PrivateDevices=yes
SecureBits=keep-caps
AmbientCapabilities=CAP_IPC_LOCK CAP_NET_BIND_SERVICE
CacheDirectory=coder
CapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK CAP_NET_BIND_SERVICE
KillSignal=SIGINT
KillMode=mixed
NoNewPrivileges=yes
ExecStart=/opt/coder/coder server
Restart=on-failure
RestartSec=5
TimeoutStopSec=90

[Install]
WantedBy=multi-user.target

要点说明：

Type=notify 依赖 Coder 的 sd_notify 支持，启动就绪后 systemd 才认为服务启动完成；
KillSignal=SIGINT 让 Coder 走优雅退出流程，TimeoutStopSec=90 给未完成的 Terraform 任务留出收尾时间；
ProtectSystem=full 会把 /usr、/boot、/etc 置为只读，因此配置只读、缓存必须落到 CacheDirectory；
AmbientCapabilities=CAP_NET_BIND_SERVICE 允许非 root 绑定 1024 以下端口（本文用 3000，不依赖此能力，但保留以便改用 443）。

5.5 启动

systemctl daemon-reload
systemctl enable --now coder
systemctl is-active coder
# active

启动日志中会明确打印监听地址：

Started HTTP listener at http://0.0.0.0:3000

5.6 创建管理员

create-admin-user 是 coder server 的子命令，会直接读写数据库，因此必须带上 CODER_PG_CONNECTION_URL：

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"'

六、方案 C：deb 包安装

6.1 安装

curl -fL -o /tmp/coder_2.37.7_linux_amd64.deb \
  https://github.com/coder/coder/releases/download/v2.37.7/coder_2.37.7_linux_amd64.deb

dpkg -i /tmp/coder_2.37.7_linux_amd64.deb

实测回显：

Selecting previously unselected package coder.
Unpacking coder (2.37.7-1) ...
Setting up coder (2.37.7-1) ...

Configuration file '/etc/coder.d/coder.env'
 ==> File on system created by you or by a script.
 ==> File also in package provided by package maintainer.
 ==> Keeping old config file as default.

出现配置文件提示说明本机已存在同路径文件，包管理器保留了旧文件（dpkg -i 的默认行为）。此时务必检查旧文件里是否仍是要用的配置。

dpkg -l coder
# ii  coder  2.37.7-1  amd64  Provision development environments with infrastructure with code
/usr/bin/coder version

6.2 包内布局

deb 包会：

安装二进制到 /usr/bin/coder；
创建系统用户 coder（User=coder / Group=coder）；
安装加固版 systemd 单元到 /lib/systemd/system/coder.service，同样使用 Type=notify、EnvironmentFile=/etc/coder.d/coder.env、ProtectSystem=full、PrivateTmp、AmbientCapabilities；
放置配置模板 /etc/coder.d/coder.env。

包内 coder.env 模板内容（关键项默认为空，必须自行填写）：

# Coder must be reachable from an external URL for users and workspaces to connect.
# e.g. https://coder.example.com
CODER_ACCESS_URL=

CODER_HTTP_ADDRESS=
CODER_PG_CONNECTION_URL=
CODER_TLS_CERT_FILE=
CODER_TLS_ENABLE=
CODER_TLS_KEY_FILE=

6.3 填写配置并启动

cat > /etc/coder.d/coder.env <<'EOF'
CODER_HTTP_ADDRESS=0.0.0.0:3000
CODER_ACCESS_URL=http://192.168.1.71:3000
CODER_PG_CONNECTION_URL=postgres://coder:q1w2e3r4@127.0.0.1:5432/coder?sslmode=disable
CODER_LOGGING_HUMAN=/dev/stdout
EOF

systemctl daemon-reload
systemctl enable --now coder
systemctl status coder --no-pager

实测 systemctl status 关键行：

● coder.service - Coder control plane
     Active: active (running) since Tue 2026-10-27 17:26:52 UTC; 42s ago
       Docs: https://coder.com/docs
     Memory: 773.4M
        CPU: 5.838s

单元路径随安装方式不同：自建单元在 /etc/systemd/system/coder.service，deb 包单元在 /lib/systemd/system/coder.service，可用 systemctl show -p FragmentPath coder 确认实际加载的是哪一个。

6.4 卸载

systemctl disable --now coder
dpkg -r coder
# Removing coder (2.37.7-1) ...

实测卸载后 /usr/bin/coder 与 systemd 单元同时消失。deb 包不会删除 /etc/coder.d 下的配置，也不会删除数据库，需要手工清理。

七、三种方案对比

维度	方案 A：install.sh	方案 B：tar.gz + 自建 systemd	方案 C：deb 包
联网要求	需访问 GitHub	可离线拷贝压缩包	可离线拷贝 deb
安装内容	仅二进制	二进制 + 自建用户/单元/配置	二进制 + 用户 + 加固单元 + 配置模板
系统集成度	低	中（取决于自建单元）	高
升级方式	重跑脚本	替换二进制 + 重启	`dpkg -i` 新版本
卸载干净度	手工删文件	手工删文件	`dpkg -r` + 手工清配置/数据
适用场景	快速体验、尝鲜	离线、自定义布局、非 deb 发行版	标准化生产、需要包管理审计

选型建议：生产优先方案 C（包管理可审计、单元已加固）；需要固定目录或离线交付选方案 B；临时验证选方案 A。

八、关键配置说明

8.1 必填三项

环境变量	本文取值	说明
`CODER_ACCESS_URL`	`http://192.168.1.71:3000`	用户与 agent 回连的地址，生产建议 HTTPS 域名
`CODER_HTTP_ADDRESS`	`0.0.0.0:3000`	HTTP 监听地址，默认 `127.0.0.1:3000`，只监听回环时外部无法访问
`CODER_PG_CONNECTION_URL`	`postgres://coder:q1w2e3r4@127.0.0.1:5432/coder?sslmode=disable`	数据库连接串，同机可关闭 SSL

8.2 可选但建议

CODER_LOGGING_HUMAN=/dev/stdout：让日志进入 systemd journal，便于 journalctl -u coder 统一检索；默认是 /dev/stderr；
CODER_CACHE_DIRECTORY=/var/cache/coder：与 systemd 的 CacheDirectory 对齐，避免缓存写进用户主目录；
CODER_TLS_ENABLE + CODER_TLS_CERT_FILE + CODER_TLS_KEY_FILE：由 Coder 自己终止 TLS；若前置反向代理终止 TLS，则保持关闭；
CODER_WILDCARD_ACCESS_URL=*.example.com：启用工作区应用的子域名访问，需要通配 DNS 与证书。

8.3 YAML 配置文件

除环境变量外，Coder 还支持 -c/--config 指定 YAML 文件。该能力在 2.37.7 启动时会打印：

WARN: YAML support is experimental and offers no compatibility guarantees.

生产环境建议以环境变量为主、YAML 为辅；YAML 的字段结构、优先级与完整模板见《Coder 2.37.7 配置参数详解》。

九、安装验证

# 1. 服务状态
systemctl is-active coder
# active

# 2. 健康检查
curl -s http://127.0.0.1:3000/healthz
# OK

# 3. HTTP 可达性
curl -sI http://192.168.1.71:3000 | head -n 3
# HTTP/1.1 200 OK
# Accept-Ranges: bytes
# Content-Type: text/html; charset=utf-8

# 4. 版本与数据库连通性
coder version
coder provisioner list

coder provisioner list 出现 3 个 built-in 守护进程且状态为 idle，说明控制面、数据库与内置 provisioner 均已就绪。完整 CLI 用法见《Coder 2.37.7 常用 CLI 与运维命令详解》。

十、FAQ

10.1 端口被占用

error: configure http(s): listen tcp 127.0.0.1:3000: bind: address already in use

处理：ss -ltnp 找到占用进程并停掉，或改用其他端口并同步修改 CODER_ACCESS_URL。

10.2 数据库密码错误

2026-10-27 ... [warn]  ping postgres: retrying  error="pq: password authentication failed for user \"coder\""  try=1
...
error: connect to postgres: connect to postgres: unable to connect after 11 tries; last error: pq: password authentication failed for user "coder"

Coder 会以递增间隔重试 11 次后退出。排查顺序：连接串密码是否正确、是否有 URL 编码、pg_hba.conf 对 127.0.0.1/32 是否允许 scram-sha-256、角色是否存在。

10.3 access-url 未带 scheme

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

CODER_ACCESS_URL 必须写成 http://host:port 或 https://host，不能只写 IP 或域名。

10.4 没设 access-url 会怎样

启动时会自动开启 try.coder.app 隧道，日志提示：

Opening tunnel so workspaces can connect to your deployment. For production scenarios, specify an external access URL

隧道地址是临时的，仅适合本地验证；生产必须显式设置 CODER_ACCESS_URL。

10.5 新建用户密码总被拒绝

实测：用 create-admin-user 创建 admin 时，密码 q1w2e3r4 可以成功；但用 coder users create 新建普通用户时，同样的小写密码会被密码策略拒绝，改成 Q1w2e3r4! 才能通过。原因是管理员创建路径与普通用户创建路径的策略校验不同。建议：

管理员首次口令可以用简单口令，登录后立即修改；
批量创建普通用户时统一使用「大写 + 小写 + 数字 + 符号」的 8 位以上口令，例如 Q1w2e3r4!；
生产环境应接入 OIDC 并考虑关闭密码登录（CODER_DISABLE_PASSWORD_AUTH=true）。

10.6 首次启动提示 YAML 实验特性

见 8.3。该警告只在使用 -c 加载 YAML 时出现，不影响功能，但官方不保证跨版本兼容。

10.7 数据如何备份

Coder 的全部业务数据都在 PostgreSQL 中，备份数据库即可：

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

工作区内部的数据不在控制面，需由模板自身的存储方案负责。

10.8 能否与 code-server 共存

可以。Coder 工作区内部通常运行 code-server 或 SSH 服务；两者监听端口不同即可。单机同时运行时注意 3000/8080 端口与内存分配。

十一、卸载与清理

方案 A/B：

systemctl disable --now coder
rm -f /etc/systemd/system/coder.service
systemctl daemon-reload
rm -rf /opt/coder /usr/local/bin/coder /etc/coder.d /var/cache/coder /var/lib/coder
userdel coder

方案 C：

systemctl disable --now coder
dpkg -r coder
rm -rf /etc/coder.d

数据库清理（谨慎，先备份）：

sudo -u postgres psql -c 'DROP DATABASE coder;'
sudo -u postgres psql -c 'DROP ROLE coder;'

十二、参考链接

官方安装文档：https://coder.com/docs/install
官方安装脚本：https://coder.com/install.sh
外部数据库要求：https://coder.com/docs/tutorials/external-database
PostgreSQL PGDG 仓库：https://apt.postgresql.org/
GitHub Releases：https://github.com/coder/coder/releases
站内：《Coder 介绍与选型指南》、《Coder 2.37.7 配置参数详解》、《Coder 2.37.7 常用 CLI 与运维命令详解》