setup

设置

安装 Coder 并完成首次运行设置，无需让用户 学习命令行或 Web UI。

信息来源

使用特定主题的详细信息前，请先阅读上游最新文档：

• https://coder.com/docs/llms.txt，查看文档索引。
• 仅当索引信息不足时，才查看 https://coder.com/docs/llms-full.txt。

大多数产品详情都应以上游文档为准，而非本技能。请自行查阅文档，了解安装方法、Helm 值、TLS、通配符域名、模板、OIDC、OAuth、外部配置器、升级、备份、遥测和 Premium 功能，并按文档执行；除非用户明确要求，否则不要让用户自行查阅文档。

本技能仅保留安装流程、用户交互规则和少量设置相关注意事项。

用户交互

用户要的是可用的 Coder 部署，而不是 Coder 教程。 保持消息简短直白：

• 除非使用结构化选择器，否则每次只询问一个决定。
• 优先给出合理的默认选项，再请用户确认。
• 如果用户是新手，先解释 Coder 的概念，再说出其名称。
• 不要在面向用户的问题和交接内容中提及标志、环境变量、配置键、原始日志和文档 URL。
• 不要向用户提及“技能”或“设置技能”。
• 不要把命令行操作教程作为后续步骤；改用通俗语言表示可以继续协助。

实用释义：

• 访问 URL：用户打开以使用 Coder 的网页地址。
• 通配符 URL：通过 DNS 为工作区内的应用分配各自子域名。
• 工作区：供一个人使用的开发环境。
• 模板：Coder 用来构建工作区的配方。
• 所有者：第一个管理员账户。
• 外部身份验证：允许工作区登录 GitHub、GitLab 等服务，以便克隆私有仓库。

如果用户询问实现细节，本轮请用技术语言回答，然后继续使用通俗语言交流。

工作流程

每个阶段都有退出条件。执行可能造成破坏的操作前，请先确认，例如安装系统软件包、开放端口、覆盖 kubeconfig、删除卷或替换现有 Coder 状态。

1. 了解情况

在探测主机前，先获得以下五项信息：

1. 他们以前用过 Coder 吗？
2. 这是快速入门／演示，还是长期／团队部署？
3. Coder 应该运行在哪里：Docker、Kubernetes／Helm、主机上，还是其他环境？
4. 第一个管理员应使用 GitHub 还是电子邮件／密码登录？
5. 设置是否应推送一个入门开发环境并创建第一个工作区？

如果有可用的结构化提问工具，请使用它。如果该工具一次最多只能提问四项，先一起询问前四项，再单独询问工作区相关问题。如果没有结构化工具，则在一条简洁的聊天消息中询问全部五项。

收到回答后，静默探测：

uname -sm
command -v apt-get dnf yum apk brew zypper pacman 2>/dev/null
docker version --format '{{.Server.Version}}' 2>/dev/null
kubectl config current-context 2>/dev/null
helm version --short 2>/dev/null
coder --version 2>/dev/null
systemctl is-active coder 2>/dev/null
test -f "$HOME/.config/coderv2/url" && cat "$HOME/.config/coderv2/url"
env | grep -E '^(CODER_AGENT_TOKEN|CODER_WORKSPACE_NAME)=' || true

然后用一小段话说明计划，并在修改系统前询问用户是否同意。

对应方案：

• 快速入门／演示：默认使用内置的 *.try.coder.app 隧道。
• 生产／团队部署：收集域名、HTTPS 方案、Postgres 选择、通配符偏好和服务管理器信息。提出计划前，阅读最新的安装和管理员设置文档。
• Docker、Kubernetes／Helm 和直接安装到主机上均可执行。
• Rancher、OpenShift、云市场和隔离网络安装必须遵循其最新文档，不要依赖记忆中的操作方案。
• 直接安装仍可推送 Docker 入门环境（如果已安装 Docker）；没有有效的 kube 上下文时，不要选择 Kubernetes。
• 在无头模式下，将用户的原始请求视为批准，默认使用电子邮件／密码登录；如果缺少生产环境所需信息，则快速失败。

如果存在先前的快速入门状态，而用户正要迁移到生产环境，请询问是否停止它。使用其 PID、compose、systemd 或 Helm 句柄；绝不要使用不加区分的 pkill coder。

2. 安装

安装前，检查当前 shell 是否已位于 Coder 工作区内：

test -n "${CODER_AGENT_TOKEN-}${CODER_WORKSPACE_NAME-}"

如果是，除非用户明确要求嵌套 Coder，否则拒绝在主机上安装。在指定目录中使用 Docker compose，或针对单独的集群上下文使用 Helm，都是可接受的。

直接安装时，使用规范安装程序：

curl -fsSL https://coder.com/install.sh | sh

在用户本地安装时：

curl -fsSL https://coder.com/install.sh \
  | sh -s -- --method standalone --prefix "$HOME/.local"
export PATH="$HOME/.local/bin:$PATH"

对于 Docker compose 和 Helm，阅读当前上游安装页面并按其说明操作。对于生产环境，除非用户另有要求，否则优先使用稳定版本。使用 coder --version 验证阶段。

3. 启动

为生成的文件创建一个状态目录：

STATE_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/coder-install"
mkdir -p "$STATE_DIR"

在主机上直接启动以快速开始：

nohup coder server > "$STATE_DIR/server.log" 2>&1 &
echo $! > "$STATE_DIR/server.pid"

快速启动隧道不要传入访问 URL。解析服务器日志中 View the Web UI: 后的那一行，并等待 /healthz。如果隧道无法初始化，则使用 http://localhost:7080 和 --http-address 0.0.0.0:7080 重启；工作区容器无法访问仅绑定到主机环回地址的服务。

对于 Docker compose、systemd 和 Helm，让相应的管理器负责进程和日志。对于生产环境，根据当前文档配置清单或服务环境，然后等待公共 URL 上的 /healthz。如果配置了通配符 DNS，请验证其是否正常。

4. 创建管理员

第一个用户将成为 Owner。

登录前，保护现有 CLI 会话。只有当默认配置已指向另一个真实部署时，才设置隔离的 CODER_CONFIG_DIR：

default_dir="${XDG_CONFIG_HOME:-$HOME/.config}/coderv2"
if [ -f "$default_dir/url" ]; then
  existing="$(cat "$default_dir/url")"
  case "$existing" in
    "$ACCESS_URL"|"") : ;;
    *)
      export CODER_CONFIG_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/coderv2-quickstart"
      export CODER_CACHE_DIRECTORY="${XDG_CACHE_HOME:-$HOME/.cache}/coderv2-quickstart"
      mkdir -p "$CODER_CONFIG_DIR" "$CODER_CACHE_DIRECTORY"
      ;;
  esac
fi

对于新部署，如果可用，优先使用 GitHub 设备流。检查 /api/v2/users/authmethods 和 /api/v2/users/oauth2/github/device；如果任一接口表明设备流不可用，则改用电子邮件／密码。

分三个不同步骤运行设备流：

1. 运行 scripts/github-device-fetch.sh。
2. 在聊天中向用户发送验证 URL 和代码，然后等待确认。
3. 运行 scripts/github-device-poll.sh。

不要在同一次 shell 调用中同时执行 fetch 和 poll；工具运行器通常会缓冲标准输出，直到 poll 退出。只有在流程失败或需要了解协议详情时，才阅读 references/first-user-github-device.md。

使用电子邮件／密码时，生成强密码，通过环境变量传递，并始终禁用上游企业试用提示：

export CODER_FIRST_USER_PASSWORD="$PASSWORD"
coder login "$ACCESS_URL" \
  --first-user-email "$EMAIL" \
  --first-user-username "$USERNAME" \
  --first-user-full-name "$FULL_NAME" \
  --first-user-trial=false
unset CODER_FIRST_USER_PASSWORD

将生成的凭据以 0600 权限保存在 $STATE_DIR 下，并使用 coder whoami 和 coder users list 验证。

5. 推送入门模板

选择与所选基础设施相匹配的入门模板。在假定 ID 或必需变量之前，先阅读当前模板文档。

TEMPLATE_DIR="$(mktemp -d)/$TEMPLATE_NAME"
coder templates init --id "$TEMPLATE_ID" "$TEMPLATE_DIR"
coder templates push "$TEMPLATE_NAME" -d "$TEMPLATE_DIR" --yes
coder templates list

非机密值使用变量文件。绝不要回显机密信息、将其放入 terraform.tfvars，或将其作为纯文本 --variable 值传递；如果凭据必须保留在服务器之外，请使用 Coder 的机密变量模式或外部配置器。

6. 构建工作区

如果用户拒绝创建第一个工作区，则跳过此阶段。

在执行 coder create 之前，拉取模板并检查 data "coder_parameter" 块：

TEMPLATE_PULL="$(mktemp -d)/$TEMPLATE_NAME"
coder templates pull "$TEMPLATE_NAME" "$TEMPLATE_PULL"

明确传入每个必需参数。对于“无”是显而易见的取值的必需列表参数，使用 []；对于简单的单选枚举，使用第一个选项；只有在不存在合理取值时才询问用户。

coder create "$WORKSPACE_NAME" \
  --template "$TEMPLATE_NAME" \
  --parameter 'jetbrains_ides=[]' \
  --yes

等待工作区 Agent 达到 ready 状态；构建成功还不够。如果 Agent 一直处于 connecting 状态，请阅读 references/troubleshooting.md。

7. 交接

最后用一段简短的纯英文内容说明：

• 浏览器 URL。
• 登录凭据，或确认已完成 GitHub 登录。
• 安装程序将本地文件写入的位置。
• 恰好一条日志命令和一条停止命令，且必须与实际使用的管理方式匹配：宿主机 PID/日志、Docker compose、systemd 或 Helm。
• 是否已创建 starter 工作区。
• 用一句话表示可以协助配置 Coder Agents。

不要包含文档 URL、原始上游 .md 链接、其他命令占位符，也不要列出一系列供用户尝试的 CLI 命令。

如果用户接受配置 Coder Agents 的提议，请阅读 references/coder-agents.md 并遵循其中的步骤。不要要求用户将 LLM API 密钥粘贴到聊天中；请让他们在 shell 中导出密钥，并从环境变量中读取。

安全措施

• 不要假设使用 Docker。询问 Coder 应该在哪里运行。
• 不要不加区分地终止 coder 进程，尤其是在 Coder 工作区内。
• 未经明确批准，不要执行破坏性清理。
• 除非现有登录指向其他位置，否则不要隔离 CODER_CONFIG_DIR。
• 不要让用户选择试用版或 Premium 注册；传递 --first-user-trial=false。
• 不要代替用户禁用遥测。
• 不要跳过 /healthz 就绪检查。
• 不要遗留 GitHub 设备授权流程的 cookie jar 或 env 文件。
• 不要打印管理员密码、OAuth 密钥、云凭据或 LLM API 密钥。

如果设置过程卡住，请阅读 references/troubleshooting.md，再开始排查。 该文档涵盖工作区主机保护、Docker 网桥连通性、NixOS 防火墙行为、ARM 上的内嵌 Postgres、Terraform 安装程序签名失败、Docker 组刷新、Caddy 重定向循环，以及 tailnet DNS 重绑定保护。

捆绑资源

仅在触发条件满足时加载：

• references/first-user-github-device.md： GitHub 设备代码协议及故障。触发条件：设备登录失败或需要了解详细信息。
• references/coder-agents.md： Coder Agents 提供商/模型设置。触发条件：用户接受配置 Agents 的提议。
• references/troubleshooting.md： 上游文档未充分涵盖的设置相关故障。触发条件：安装、服务、模板或工作区就绪状态卡住。
• scripts/github-device-fetch.sh： 获取 GitHub 设备代码并写入 $STATE_DIR/github-device.*。
• scripts/github-device-poll.sh： 轮询 GitHub 授权状态、写入 Coder 会话，并清理临时文件。