code-server 官方 FAQ 全解：配置文件、密码认证、扩展市场、心跳与排障的权威答案

本篇基于 code-server 仓库的 FAQ 文档 整理扩写，覆盖配置文件机制、密码与 Argon2 哈希认证、Open-VSX 扩展市场、/healthz 健康检查、心跳文件、代理与调试等高频问题，并结合 src/node/cli.ts、src/node/util.ts、src/node/heart.ts 等源码逐条印证，帮助你把 code-server 的部署、认证与运维细节一次吃透。

一、配置文件如何工作

code-server 首次启动时会在 ~/.config/code-server/config.yaml 生成默认配置文件：

bind-addr: 127.0.0.1:8080
auth: password
password: mew...22 # 每次生成为随机值
cert: false

默认配置的行为是：监听回环地址 8080 端口、启用密码认证、不使用 TLS。

配置文件里每一个键都直接映射为一个命令行 flag（运行 code-server --help 可查看全部 flag），且命令行传入的 flag 优先于配置文件。可以用 --config flag 或 $CODE_SERVER_CONFIG 环境变量指定其他位置，默认位置遵循 $XDG_CONFIG_HOME 约定。

从源码看，这一机制在 src/node/cli.ts 中实现：

• defaultConfigFile() 生成上面那段默认 YAML，密码由 generatePassword() 随机产生；
• readConfigFile() 优先读取 $CODE_SERVER_CONFIG，否则回落到 paths.config 目录下的 config.yaml，并以 wx 标志写入默认文件（文件已存在则不覆盖）；
• parseConfigFile() 用 js-yaml 解析 YAML 后，把每个键转换成 --键名=值 形式的虚拟命令行参数再统一解析。所以配置文件本质上就是"持久化的命令行参数"，这也是"任何 flag 都能在配置文件里写"的原因。

二、如何修改端口

两种方式：

1. 环境变量：PORT=3000 code-server
2. flag：code-server --bind-addr localhost:3000

源码侧，bindAddrFromArgs 的合并优先级为：--bind-addr 整体解析 host 与 port，$CODE_SERVER_HOST 覆盖 host，$PORT 覆盖 port，--port 再次覆盖。注意 parseBindAddr 中若 --bind-addr 省略端口，会默认解析为 80 而非 8080。

三、密码认证：明文、Argon2 哈希与限流

3.1 修改密码

编辑 ~/.config/code-server/config.yaml 中的 password 字段后重启，例如 systemd 场景：

sudo systemctl restart code-server@$USER

密码只能通过配置文件或 $PASSWORD 环境变量传入。src/node/cli.ts 中 parse 会显式拒绝 --password 出现在命令行上（报错 "can only be set in the config file or passed in via $PASSWORD"），`--hashed-password` 同理（仅允许 `$HASHED_PASSWORD` 或配置文件），避免密码进入 shell 历史记录与进程列表。

3.2 以哈希形式存储密码

在配置中使用 hashed-password 代替 password，用 argon2 生成哈希：

echo -n "thisismypassword" | npx argon2-cli -e
# $argon2i$v=19$m=4096,t=3,p=1$wst5qhbgk2lu1ih4dmuxvg$ls1alrvdiwtvzhwnzcm1dugg+5dto3dt1d5v9xtlws4

记得把实际密码放进引号，然后写入配置：

auth: password
hashed-password: "$argon2i$v=19$m=4096,t=3,p=1$wST5QhBgk2lu1ih4DMuxvg$LS1alrVdIWtvZHwnzCM1DUGg+5DTO3Dt1d5v9XtLws4"

hashed-password 的优先级高于 password。若使用 Docker Compose，所有 $ 需写成 $$ 转义，例如：

- HASHED_PASSWORD=$$argon2i$$v=19$$m=4096,t=3,p=1$$wST5QhBgk2lu1ih4DMuxvg$$LS1alrVdIWtvZHwnzCM1DUGg+5DTO3Dt1d5v9XtLws4

实现上，src/node/util.ts 的 getPasswordMethod 按三种方式区分认证算法：哈希中包含 $argon 判定为 ARGON2；否则若设置了哈希则按遗留的 SHA256 处理；都没有则为 PLAIN_TEXT。登录校验由 handlePasswordValidation 执行：明文模式用常量时间比较 safeCompare，Argon2 模式调用 argon2.verify（isHashMatch），并把哈希值写入会话 Cookie。此外登录页做了防爆破限流：每分钟最多 2 次、每小时最多再 12 次，登录接口见 src/node/routes/login.ts。

四、扩展市场：为什么不用微软官方市场

VS Code 的核心是开源的，但微软扩展市场和许多微软发布的扩展不是，且微软禁止非微软的 VS Code 客户端访问其市场（其市场使用条款明确"Marketplace Offerings 仅可与 Visual Studio 产品及服务配合使用"）。因此 code-server 改用 Open-VSX 扩展画廊（其他主流分支亦在使用），并保留了自己托管的开源扩展市场（计划未来弃用、完全迁移到 Open-VSX）。

目前因此不可用的闭源扩展包括：Live Share、Remote 系列（SSH/Containers/WSL）等。

如何安装扩展：可以在扩展侧边栏里从市场安装，也可以在命令行：

code-server --install-extension <extension id>
# 示例：code-server --install-extension wesbos.theme-cobalt2

# 从扩展市场安装
code-server --install-extension ms-python.python

# 从本地下载好的 VSIX 安装
code-server --install-extension downloaded-ms-python.python.vsix

手动安装：若某扩展市场上没有或不能工作，可以从其 GitHub Releases 下载 VSIX（或自行构建），放到远程机器上后，在命令面板执行 Extensions: Install from VSIX，或运行 code-server --install-extension <vsix 路径>。

自定义扩展市场：如果你的市场实现了 VS Code Extension Gallery API，可通过 $EXTENSIONS_GALLERY 指向它，它对应 VS Code product.json 中的 extensionsGallery 条目：

export EXTENSIONS_GALLERY='{"serviceUrl": "https://my-extensions/api"}'

技术上虽然可以这样指向微软市场，但官方强烈不建议，因为这违反其使用条款。

扩展与 VS Code 配置存储在哪里

• 扩展默认存于 ~/.local/share/code-server/extensions；
• VS Code 的设置、键位等配置默认存于 ~/.local/share/code-server；
• 在 Linux/macOS 上若设置了 XDG_DATA_HOME，对应目录为 $XDG_DATA_HOME/code-server（extensions 在其下）。总体上遵循 XDG 目录规范。

这些路径的推导见 src/node/util.ts 中基于 xdg-basedir 的 getEnvPaths，支持通过环境变量覆盖。

复用现有 VS Code 配置：可以安装 Settings Sync 扩展；或者更直接地传 --user-data-dir ~/.vscode，或把 ~/.vscode 拷贝进 ~/.local/share/code-server，从而复用既有扩展与配置。

五、工作区选择逻辑与 URL 深链

code-server 按以下顺序决定打开哪个工作区或文件夹：

1. workspace 查询参数
2. folder 查询参数
3. 命令行传入的工作区或目录
4. 上次打开的工作区或目录

通过 URL 打开指定行：除 workspace/folder 外还支持 VS Code 的 payload 查询参数，它在工作台加载后可打开特定文件（可选带行列定位）。payload 是 URL 编码后的 [key, value] 字符串对 JSON 数组，openFile 键取 vscode-remote://<host>/<绝对路径> 形式的 URI，<host> 为你访问 code-server 用的主机名；加上 ["gotoLineMode","true"] 后路径尾部的 :行[:列] 会被解释为光标位置：

https://code.example.com/?folder=/home/coder/project&payload=[["gotoLineMode","true"],["openFile","vscode-remote://code.example.com/home/coder/project/src/app.py:10:5"]]

注意路径必须是绝对路径，没有相对 folder 的相对形式；这是上游 VS Code web 的既有行为（vscode.dev 用的同一机制），无需 code-server 特有配置。一个从 shell 生成此类链接的脚本示例：

#!/bin/sh
# 用法: code-link <绝对文件路径> [行[:列]]
HOST=code.example.com
payload="[[\"gotoLineMode\",\"true\"],[\"openFile\",\"vscode-remote://$HOST$1${2:+:$2}\"]]"
printf 'https://%s/?folder=%s&payload=%s\n' "$HOST" "$(dirname "$1")" \
  "$(printf '%s' "$payload" | jq -sRr @uri)"

六、健康检查：healthz 端点与心跳文件

6.1 /healthz 端点

无需认证即可访问，用于在不触发心跳的情况下检查 code-server 是否存活，响应包含状态（alive 或 expired）与最近一次心跳时间戳（默认 0）：

{
  "status": "alive",
  "lastHeartbeat": 1599166210566
}

实现见 src/node/routes/health.ts：HTTP GET /healthz 与 WebSocket 升级都直接读取 req.heart 的 alive() 与 lastHeartbeat 返回 JSON，不产生任何副作用。

6.2 心跳文件

只要存在活跃的浏览器连接，code-server 就会每分钟 touch 一次 ~/.local/share/code-server/heartbeat 文件。若想"空闲一段时间后自动关闭"，可传 --idle-timeout-seconds flag 或设置环境变量 CODE_SERVER_IDLE_TIMEOUT_SECONDS（源码见 src/node/cli.ts，要求必须是数字且大于 60 秒）。

从 src/node/heart.ts 的实现看：Heart.beat() 在存活窗口（heartbeatInterval = 60000 毫秒）内不重复写文件，过期后重写并启动一个 60 秒的定时器，到期时若 isActive()（是否存在活跃连接）仍为真则继续 beat，否则把状态置为 expired。这解释了 healthz 中 alive 的判定条件 now - lastHeartbeat < 60000。

6.3 重连宽限期

可通过三种方式设置 --reconnection-grace-time <秒数>、CODE_SERVER_RECONNECTION_GRACE_TIME=<秒数> 或写入配置文件 reconnection-grace-time: <秒数>。默认 10800（3 小时）：客户端断连超过该时长后必须刷新窗口才能恢复。

七、代理：请求代理与端口代理

7.1 服务端请求走代理

code-server 只代理服务端发出的请求，支持以下环境变量：$HTTP_PROXY、$HTTPS_PROXY、$NO_PROXY：

export HTTP_PROXY=https://134.8.5.4
export HTTPS_PROXY=https://134.8.5.4
# 此后 code-server 的所有服务端请求都会先经过 https://134.8.5.4
code-server

语法细节遵循 proxy-from-env 的约定（code-server 仅使用 http 与 https 协议）；支持的代理协议可参考 proxy-agent。源码上，src/node/constants.ts 的 httpProxyUri 会依次读取 HTTPS_PROXY/https_proxy/HTTP_PROXY/http_proxy。

7.2 禁用端口转发代理

传 --disable-proxy flag，或设 CS_DISABLE_PROXY=1 / CS_DISABLE_PROXY=true。注意：该选项只禁用了转发端口的 domain 与 path 代理路由（含 HTTP 与 WebSocket），不会关闭 VS Code 工作台自身的自动端口转发——Ports 面板与提示仍会出现，只是实际无法访问。建议同时把 remote.autoForwardPorts 设为 false。相关路由实现见 src/node/routes/domainProxy.ts 与 src/node/routes/pathProxy.ts。

八、调试与排障

1. 用 --log debug（或 --log trace 更彻底）启动；-vvv 与 --verbose 是 --log trace 的别名；也可用 LOG_LEVEL 环境变量。
2. 复现问题，并从以下位置收集信息：
   • ~/.local/share/code-server/coder-logs 中最新的日志文件；
   • 浏览器控制台；
   • 浏览器网络面板。
3. 若 code-server 崩溃，收集 core dump（可能需先开启 core dump）也很有帮助。

其他排障相关 flag：

• 禁用遥测：--disable-telemetry；
• 隐藏 Getting Started 中的 coder/coder 推广：--disable-getting-started-override，或 CS_DISABLE_GETTING_STARTED_OVERRIDE=1|true；
• 禁用文件下载：--disable-file-downloads（对应 CS_DISABLE_FILE_DOWNLOADS）。

九、Web View 为什么不工作

Web View 依赖 Service Worker，而 Service Worker 只在安全上下文（secure context）可用——大概率是你用了不安全上下文（例如直接用 IP 地址访问）。此时浏览器日志中会出现类似：

Error loading webview: ... Failed to register a ServiceWorker ... An SSL certificate error occurred when fetching the script.

解决办法：

• 通过 localhost/127.0.0.1 访问（始终视为安全）；
• 使用带真实证书（如 Let's Encrypt）的域名；
• 使用 mkcert 生成并被信任的自签名证书（或手动创建并信任）；
• 若浏览器允许，直接放宽安全限制（如 Chromium 的 chrome://flags/#unsafely-treat-insecure-origin-as-secure）。

十、平台与部署相关问题

• 暴露到互联网：务必遵循仓库中的安全暴露指南 docs/guide.md，不要直接裸奔公网。
• iPad 使用：详见 docs/ipad.md。
• macOS 访问 Desktop/Documents/Downloads：新版 macOS 对这些目录采用非 UNIX 的权限机制，Node.js 本身不实现 macOS 权限请求，通常需要给 Node.js 授予"完全磁盘访问"：先用 which node 找到二进制位置，再到 系统设置 > 安全性与隐私 > 隐私 > 完全磁盘访问 中添加该二进制。
• 键盘快捷键被浏览器截获：Chrome 可安装 PWA（启动编辑器后点击地址栏右侧的"加号"图标安装）；Firefox 可安装 PWA 扩展并按其说明安装运行时配套组件；其他浏览器则需自行重映射键位。
• 多租户：官方推荐在共享基础设施上为每个用户单独提供一台虚拟机（用户可在其中运行 Docker daemon）；用 Kubernetes 时建议结合 kubevirt 或 sysbox 这类提供 VM 级隔离的方案，而不是单纯容器。
• 在 code-server 容器里用 Docker：把宿主机的 /var/run/docker.sock 挂载进容器，并在容器内安装 Docker CLI 即可访问 daemon；若要让 volume 挂载在容器间生效，需保证 Docker daemon 与 code-server 容器看到的同一宿主路径完全一致。Kubernetes 部署时关注 helm values 文件 中的 extraVars、lifecycle.postStart 与 extraContainers 三个字段。

十一、code-server 与其他方案的区别

• vs Coder：两者都可装在任意机器上。code-server 开箱即用就是"浏览器里的 VS Code"，面向个人；Coder 是用 Terraform 编排远程开发环境（Workspace）的团队工具，Workspace 中可运行 code-server 等应用。
• vs Theia：code-server 是对 VS Code 做补丁的分支，在浏览器中运行；Theia 只复用了 VS Code 的 Monaco 编辑器与扩展 API，其余是另一个 IDE，且不能复用现有 VS Code 配置。Theia 同样使用 Open-VSX 市场。
• vs OpenVSCode-Server：后者直接 fork VS Code 并在上游提交修改，目标仅是把原版 VS Code 搬进浏览器；code-server 通过 submodule 引入 VS Code 并以补丁文件方式修改（见 patches 目录），额外做了大量自托管体验增强：密码认证、子路径部署、自包含且不外联微软服务器的 web views、自定义市场与遥测、内置远程端口代理并集成进 VS Code 端口面板、设置落盘（而非浏览器存储，但工作台状态仍在浏览器中）、按需拉起 VS Code 的 wrapper 进程与独立 CLI、更新可用通知等。
• vs GitHub Codespaces / VS Code web：Codespaces 是闭源付费服务；code serve-web 运行的 VS Code web 与上面列举的差异相同。若需要官方微软市场，VS Code web 是更合适的选择；若追求自托管、免费、开源且限制少，code-server 更合适。

十二、要点速查

主题	关键配置	说明
配置文件	~/.config/code-server/config.yaml，$CODE_SERVER_CONFIG / --config 改位置	每个键映射一个 flag，命令行优先
端口	--bind-addr host:port 或 $PORT	CODE_SERVER_HOST 覆盖 host
密码	password / hashed-password（仅配置文件或环境变量）	Argon2 哈希优先于明文；限流 2 次/分 + 12 次/时
扩展市场	$EXTENSIONS_GALLERY	默认 Open-VSX；--install-extension 支持 id 或 vsix
扩展/配置存储	~/.local/share/code-server[/extensions]	遵循 XDG，$XDG_DATA_HOME 可改
健康检查	GET /healthz	免认证，返回 alive/expired 与最后心跳时间
心跳	~/.local/share/code-server/heartbeat	有活跃连接时每分钟 touch
重连宽限	--reconnection-grace-time	默认 10800 秒（3 小时）
空闲退出	--idle-timeout-seconds / CODE_SERVER_IDLE_TIMEOUT_SECONDS	必须 > 60 秒
服务端代理	HTTP_PROXY / HTTPS_PROXY / NO_PROXY	仅作用于服务端请求
禁用端口代理	--disable-proxy / CS_DISABLE_PROXY	建议配合 remote.autoForwardPorts: false
遥测	--disable-telemetry	收集数据仅用于改进 code-server
调试	`--log debug	trace（-vvv、--verbose` 即 trace）

以上结论均可在当前仓库中验证：配置与 flag 定义见 src/node/cli.ts，路径与密码算法见 src/node/util.ts，心跳机制见 src/node/heart.ts，健康检查路由见 src/node/routes/health.ts，对 VS Code 的补丁清单见 patches 目录。