前言
code-server 已通过 Caddy 提供 HTTPS,日常可以在浏览器中使用编辑器和终端。接入 DoraTiger Auth 后,希望复用现有登录与 MFA,不再重复输入 code-server 自己的密码。
这个入口可以执行开发机上的命令,因此只向专用管理员组开放。本次沿用已有 Debian 原生 code-server 服务,在同机增加 Authentik Proxy Outpost 2026.8.5,由 Caddy 完成 Forward Auth。
一、认证与运行身份
基础安装和 HTTPS 配置见 Homelab 搭建手记(7)部署 code-server 并配置 HTTPS 访问。本文在已有服务上增加认证:
text12345浏览器 → Caddy :443 → code-server 127.0.0.1:30080 ↕ Outpost 127.0.0.1:30092 ↕ 云端 Authentik
code-server 不处理 OIDC,也不按 Authentik 用户创建 Linux 账号。通过认证的人进入的是同一个 code-server 进程、同一个系统用户的文件和终端。需要多人独立开发环境时,应分别部署实例或选择具备工作空间隔离的平台。
二、Authentik 应用配置
2.1 专用管理员组
进入“目录 → 组”,创建 debian-code-server-admins,不启用 Authentik 超级用户权限,保存后仅加入可信的开发机管理员。
2.2 Proxy Provider 与应用
在“应用程序 → 提供者 → 创建”选择 Proxy Provider:
| 字段 | 配置 |
|---|---|
| Name | doratiger-debian-code-server |
| Authentication flow | doratiger-authentication |
| Authorization flow | doratiger-provider-authorization-implicit-consent |
| Invalidation flow | doratiger-provider-invalidation |
| Mode | Forward auth (single application) |
| External host | https://code.example.com |
| Unauthenticated paths | 留空 |
| HTTP Basic 转发 | 关闭 |
保存后在应用列表选择 with existing provider,名称填 Debian · code-server,Slug 填 debian-code-server,选择刚创建的 Provider,Launch URL 填 HTTPS 入口。
进入应用的策略/组/用户绑定,添加 debian-code-server-admins,Order 为 0,启用,Negate 关闭。保存后再配置前哨。
三、本机 Proxy Outpost
3.1 云端对象
在“应用程序 → 前哨”创建 Proxy Outpost,名称 doratiger-debian-proxy,选择 code-server 应用。这里手工运行 Docker 容器,不需要让云端服务直接控制开发机 Docker。
保存后从部署说明取得该前哨的 Token。Token 只用于前哨连接身份中心,不是给浏览器使用的 API Key。
3.2 Docker Compose
在 Debian 宿主机准备目录,以下 /opt/authentik-outpost 是示例路径:
bash123sudo install -d -m 700 -o "$(id -u)" -g "$(id -g)" /opt/authentik-outpost /opt/authentik-outpost/secrets cd /opt/authentik-outpost umask 077
创建 compose.yaml:
yaml1234567services: proxy: image: ghcr.io/goauthentik/proxy:2026.8.5 restart: unless-stopped env_file: secrets/outpost.env ports: - "127.0.0.1:30092:9000"
创建 secrets/outpost.env,由管理员通过编辑器填写真实 Token,文件权限设为 600:
dotenv123AUTHENTIK_HOST=https://auth.example.com AUTHENTIK_INSECURE=false AUTHENTIK_TOKEN=REPLACE_WITH_OUTPOST_TOKEN
bash1234sudo chmod 600 secrets/outpost.env sudo docker compose config --quiet sudo docker compose up -d sudo docker compose ps
使用 --quiet 验证 Compose,不把解析后的 Token 打印出来。前哨只监听宿主机回环;本机原生 Caddy 可以访问,局域网其他机器不能直接使用这个端口。
前哨需要出站访问云端 Authentik。若 Caddy 本身在另一个容器中,127.0.0.1 的含义不同,不能原样复制这份网络配置。
四、Caddy Forward Auth
4.1 站点配置
保留原站点的 TLS、DNS-01 和其他必要配置,将认证检查放在业务反代之前。下面是站点路由的最小示例;使用 DNS Challenge 的实例保留已有 tls 块,不用本示例覆盖证书配置:
caddyfile123456789101112code.example.com { route { reverse_proxy /outpost.goauthentik.io/* 127.0.0.1:30092 forward_auth 127.0.0.1:30092 { uri /outpost.goauthentik.io/auth/caddy copy_headers X-Authentik-Username X-Authentik-Groups X-Authentik-Email } reverse_proxy 127.0.0.1:30080 } }
route 保证这些指令按书写顺序执行。前哨路径先交给前哨,其余请求先认证,再到 code-server。Header 名称沿用官方大小写。Caddy 接入文档
原站点有 /proxy/*、扩展 WebView 或 PDF 预览专用路由时,把它们放在同一认证检查之后。本次保留了原路由,不为解决页面问题创建匿名绕过路径。
4.2 验证与重载
bash123sudo caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile sudo systemctl reload caddy curl -I https://code.example.com/
未登录请求应进入认证跳转。再检查常用子路径,没有 Authentik 会话时不能直接打开编辑器或代理内容。
本次还验证了随请求伪造身份头不能绕过认证。Caddy 必须实际向前哨验证请求,不能只判断浏览器是否带有 X-Authentik-Username。
五、code-server 本地认证
5.1 配置切换
先确认前置认证生效,再修改 code-server 运行用户的 ~/.config/code-server/config.yaml。保留其他设置,只调整相关字段:
yaml123bind-addr: 127.0.0.1:30080 auth: none cert: false
auth: none 由外部认证保护这一前提决定。code-server 仍只能监听回环,不能在关闭密码后暴露 0.0.0.0。外部认证说明
重启实际管理该服务的 systemd 单元。先用 systemctl --user status 或系统级 systemctl status 确认服务归属,不同时启用两份实例。本文原实例由既有 systemd 服务恢复运行,没有新增第二套进程管理。
5.2 功能检查
用无痕窗口访问,完成 DoraTiger Auth 登录后应直接进入编辑器。本次已确认编辑器与终端可用。进一步检查打开项目、终端命令、扩展面板、WebSocket 和常用预览路径;登录页能打开不足以验证开发功能。
六、维护与回退
备份 Caddyfile、code-server 原配置和前哨部署文件。Token 文件保存在受限目录,不进入公开仓库。
撤除前置认证前,先把 code-server 恢复为密码认证并验证,再移除 Caddy 的认证路由。不能先去掉前哨检查、留下 auth: none 的编辑器入口。
增加组成员就相当于允许对方使用这个开发环境,不能把它当成只读网站访问权限。移出组后还要处理现有会话与终端,不能假设正在运行的命令会自动结束。
七、配置问题与解答
7.1 为什么单独运行本机前哨
Q:已有 NAS 前哨,是否必须复用?
不必须。本机前哨让 Caddy 通过回环完成认证检查,不需要额外开放 NAS 前哨端口。它仍连接同一个云端 IdP,登录身份和流程没有分裂成两套。
7.2 是否产生多个 code-server 用户
Q:不同 Authentik 用户能否得到各自的 home 目录?
此方案不会。Forward Auth 只控制入口,后端仍使用原系统用户。不要以为创建多个访问组成员就获得了操作系统隔离。
7.3 子路径是否可以跳过认证
Q:扩展预览失败,能否直接放行 /proxy/*?
不应把可访问本机服务的代理路径整体匿名开放。应检查 WebSocket、路径转发和 HTTPS 安全上下文,保持它与主编辑器同样经过认证。
参考
支付宝
微信