代理架构

相关源文件

• CHANGELOG.md
• ci/helm-chart/Chart.yaml
• ci/helm-chart/values.yaml
• docs/README.md
• docs/collaboration.md
• docs/helm.md
• docs/manifest.json
• docs/requirements.md
• src/node/main.ts
• src/node/routes/domainProxy.ts
• src/node/routes/errors.ts
• src/node/routes/index.ts
• src/node/routes/pathProxy.ts
• src/node/routes/vscode.ts
• src/node/wsRouter.ts
• test/unit/node/cli.test.ts
• test/unit/node/proxy.test.ts

本文档描述了 code-server 的代理架构，详细介绍了 code-server 如何使用相同的身份验证层使用户能够访问服务器上运行的 Web 服务和应用程序。代理系统允许用户在浏览器中直接与本地运行的服务进行交互，而无需额外的身份验证或端口转发。

有关身份验证的信息，请参阅 身份验证系统。

概述

Code-server 的代理架构允许用户安全地访问安装了 code-server 的服务器上运行的 Web 服务。这对于预览 Web 应用程序、访问文档服务器、数据库接口或服务器上本地运行的任何其他 Web 服务非常有用。

来源： src/node/routes/index.ts107-119 src/node/routes/pathProxy.ts19-51 src/node/routes/domainProxy.ts56-101

代理类型

Code-server 实现了两种不同的代理类型

基于路径的代理

基于路径的代理允许通过以下格式的 URL 访问服务

• https://code-server-domain/proxy/<port>/path
• https://code-server-domain/absproxy/<port>/path （用于绝对路径代理）

基于域名的代理

基于域名的代理允许通过子域名模式进行访问，例如

• https://<port>.code-server-domain
• 带模板的域名模式： https://app-{{port}}.example.com

来源： src/node/routes/pathProxy.ts1-73 src/node/routes/domainProxy.ts1-118

实现细节

基于路径的代理实现

基于路径的代理实现在 pathProxy.ts 文件中，提供了两个主要函数：

1. proxy()：处理 HTTP 请求
2. wsProxy()：处理 WebSocket 连接

两个函数都执行以下步骤：

1. 确保代理已启用
2. 验证身份验证（除非跳过预检请求）
3. 根据请求设置路径重写
4. 将请求转发到目标服务

来源： src/node/routes/pathProxy.ts19-51 src/node/routes/pathProxy.ts53-73

基于域名的代理实现

基于域名的代理实现在 domainProxy.ts 中。它

1. 注册 HTTP 和 WebSocket 路由的处理器
2. 将传入的请求与配置的域名模式进行匹配
3. 如果匹配，则从域名中提取端口号
4. 将请求转发到相应的本地服务

域名模式使用 --proxy-domain 标志进行配置，并且可以包含模板变量

• {{port}}：替换为实际的端口号
• {{host}}：可以匹配任何主机（用于通配符 DNS 设置）

来源： src/node/routes/domainProxy.ts9-54 src/node/routes/domainProxy.ts56-101

WebSocket 代理支持

两种代理类型都支持 WebSocket 连接，允许实时应用程序通过代理工作。WebSocket 处理遵循与 HTTP 请求类似的模式，但对 WebSocket 协议有特定考虑。

来源： src/node/routes/pathProxy.ts53-73 src/node/routes/domainProxy.ts103-118

配置选项

代理系统可以通过各种命令行选项和环境变量进行配置

选项	描述
--proxy-domain	用于基于域名的代理的域名
--disable-proxy	完全禁用代理功能
--abs-proxy-base-path	为绝对代理设置基路径
--skip-auth-preflight	允许 OPTIONS 请求通过代理而不进行身份验证
VSCODE_PROXY_URI	用于端口转发模板的环境变量

配置示例

要为域名 example.com 启用基于域名的代理

code-server --proxy-domain {{port}}.example.com

在 URL 路径中直接使用代理的端口

code-server --proxy-domain app-{{port}}.example.com

来源： src/node/main.ts160-171 test/unit/node/cli.test.ts395-427 CHANGELOG.md29-30

安全考量

代理系统与 code-server 的身份验证系统集成

1. 默认情况下，所有代理的服务都需要身份验证
2. 检查请求的有效来源以防止 CSRF 攻击
3. 可以使用 --skip-auth-preflight 标志允许 OPTIONS 请求通过代理而不进行身份验证
4. 可以使用 --disable-proxy 禁用整个代理

在版本 4.5.2 中修复了一个安全漏洞，该漏洞是由于代理路由未正确执行身份验证

来源： CHANGELOG.md690-698 src/node/routes/pathProxy.ts27-40 src/node/routes/domainProxy.ts69-94

与 VS Code 的集成

代理系统也与 VS Code 的端口面板集成，允许用户直接从 VS Code 界面转发端口。此集成使用 VSCODE_PROXY_URI 环境变量，其中包含一个模板，将 {{port}} 替换为实际的端口号。

当通过端口面板转发端口时，如果通过 --proxy-domain 配置了基于域名的代理，则会使用该代理。

来源： CHANGELOG.md602-610 src/node/main.ts169-171 test/unit/node/cli.test.ts502-526

使用示例

Web 应用程序预览

在端口 3000 上开发 Web 应用程序时，可以通过以下方式访问它：

• https://code-server-domain/proxy/3000/
• https://3000.code-server-domain/ （如果配置了域名代理）

API服务器

对于运行在端口 8080 的 API 服务器

• https://code-server-domain/proxy/8080/api/data
• https://8080.code-server-domain/api/data （如果配置了域名代理）

数据库管理界面

对于端口 5432 上的数据库管理界面

• https://code-server-domain/proxy/5432/
• https://5432.code-server-domain/ （如果配置了域名代理）

结论

Code-server 的代理架构提供了一种无缝的方式，可以直接通过浏览器访问服务器上运行的 Web 服务。通过与 code-server 的身份验证系统集成，它确保了这些服务在易于访问的同时保持安全。

基于路径和基于域名的代理的双重方法提供了访问服务的灵活性，可满足不同的部署场景和用户偏好。