Proxy Service

一个独立的 Node.js / Express 代理服务。它会把访问者请求的代理入口路径转发到上游地址，并把上游响应流式返回。

成功响应不会解析 JSON、不会包装数据、不会修改响应体。上游返回字符串、JSON、HTML 或二进制内容，本服务都会尽量原样返回，并保留上游状态码与大多数响应头。

功能说明

• 默认只代理 GET /proxy/* 请求。
• 入口前缀可通过 ROUTE_PREFIX 自定义，例如 /proxy、/api、/files。
• /proxy/a/b?x=1 会转发到 UPSTREAM_BASE_URL/a/b?x=1。
• 响应体使用流式转发，不做 JSON 解析和二次序列化。
• 非 GET 请求返回 405 Method Not Allowed。
• 上游连接失败返回 502，上游超时返回 504。
• 自动过滤 hop-by-hop headers，例如 connection、transfer-encoding 等。

本地启动

安装依赖：

npm install

复制环境变量文件并按需修改：

cp .env.example .env

启动服务：

npm start

默认监听地址：

http://localhost:3000

默认访问示例：

curl -i "http://localhost:3000/proxy/demo/path?x=1"

如果配置如下：

ROUTE_PREFIX=/proxy
UPSTREAM_BASE_URL=https://example.com/path

那么实际请求的上游地址就是：

https://example.com/path/demo/path?x=1

如果想把入口改成其他路径，例如 /api：

ROUTE_PREFIX=/api

访问地址就变成：

curl -i "http://localhost:3000/api/demo/path?x=1"

环境变量

.env.example 已经为每个配置项写了中文注释。常用配置如下：

PORT=3000
ROUTE_PREFIX=/proxy
UPSTREAM_BASE_URL=https://example.com/path
PROXY_TIMEOUT_MS=30000
UPSTREAM_USER_AGENT=
UPSTREAM_REFERER=
UPSTREAM_ORIGIN=
UPSTREAM_COOKIE=
UPSTREAM_AUTHORIZATION=

配置说明：

• PORT：本服务监听端口。
• ROUTE_PREFIX：本服务对外暴露的代理入口前缀。
• UPSTREAM_BASE_URL：上游基础地址，代理会把入口前缀后面的路径拼接到这个地址后面。
• PROXY_TIMEOUT_MS：请求上游的超时时间，单位毫秒。
• UPSTREAM_USER_AGENT：可选，固定发送给上游的 User-Agent。
• UPSTREAM_REFERER：可选，固定发送给上游的 Referer。
• UPSTREAM_ORIGIN：可选，固定发送给上游的 Origin。
• UPSTREAM_COOKIE：可选，固定发送给上游的 Cookie，不要提交到 Git。
• UPSTREAM_AUTHORIZATION：可选，固定发送给上游的 Authorization，不要提交到 Git。

如果上游返回 403，通常是上游要求特定请求头或登录态。可以在 .env 里补充这些值，例如：

UPSTREAM_USER_AGENT=Mozilla/5.0
UPSTREAM_REFERER=https://example.com/
UPSTREAM_ORIGIN=https://example.com
UPSTREAM_COOKIE=
UPSTREAM_AUTHORIZATION=

Linux 一键部署 systemd

在 Linux 服务器上进入项目目录，然后执行：

bash scripts/setup-systemd.sh

脚本会自动完成：

• 如果 .env 不存在，从 .env.example 复制一份。
• 安装生产依赖：存在 package-lock.json 时使用 npm ci --omit=dev。
• 写入 systemd 配置：/etc/systemd/system/proxy-service.service。
• 执行 systemctl daemon-reload。
• 设置服务开机自启。
• 默认立即重启服务。

部署完成后常用命令：

sudo systemctl status proxy-service
sudo journalctl -u proxy-service -f
sudo systemctl restart proxy-service
sudo systemctl stop proxy-service

可以通过环境变量覆盖脚本默认值：

SERVICE_NAME=proxy-service SERVICE_USER=www-data START_NOW=0 bash scripts/setup-systemd.sh

可选参数说明：

• SERVICE_NAME：systemd 服务名，默认 proxy-service。
• SERVICE_USER：服务运行用户；用 sudo 执行脚本时，默认使用原登录用户。
• PROJECT_DIR：项目目录，默认自动识别当前脚本所在项目根目录。
• ENV_FILE：环境变量文件路径，默认使用项目目录下的 .env。
• START_NOW：是否部署后立即启动，默认 1，设为 0 时只写入并启用服务。

测试

运行自动化测试：

npm test

测试覆盖内容包括：

• 默认 /proxy/* 入口到上游路径的映射。
• 自定义 ROUTE_PREFIX。
• query string 原样保留。
• 编码路径不被解码重组。
• 上游错误状态码和响应体透传。
• 二进制响应体 byte-for-byte 透传。
• 非 GET 请求返回 405。

常见问题

返回 { "code": 1, "message": "Upstream request failed" }

说明代理服务没有成功连接到上游，常见原因是 DNS、网络、防火墙、代理环境或上游端口不可达。可以在服务器上直接测试：

curl -I "$UPSTREAM_BASE_URL"

返回 403

如果本服务返回的状态码是 403，多数情况下是上游原样返回的。请检查上游是否要求 Cookie、Authorization、Referer 或特定 User-Agent。

修改 .env 后不生效

需要重启服务：

sudo systemctl restart proxy-service

本地开发时重新执行：

npm start