jupyterhub/configurable-http-proxy

configurable-http-proxy 镜像文档

镜像概述

configurable-http-proxy（简称CHP）是一个基于https://github.com/nodejitsu/node-http-proxy的动态代理工具，通过命令行界面或REST API实现代理表的更新与管理。它支持WebSocket，适用于构建反向代理、负载均衡器等组件，特别为https://github.com/jupyterhub/jupyterhub部署提供扩展功能。

CHP运行两个HTTP(S)服务器：

• 公共接口：面向客户端的应用入口，由--ip和--port控制，默认监听所有网络接口
• REST API接口：用于内部管理代理路由，由--api-ip和--api-port控制，默认监听本地回环地址，通过CONFIGPROXY_AUTH_TOKEN环境变量进行认证

核心功能与特性

• 动态路由管理：通过REST API实时添加、删除和查询代理路由
• 双服务器架构：分离公共访问接口与管理API，提升安全性
• SSL全面支持：公共接口、API接口及客户端连接均支持SSL配置
• 自定义错误处理：支持本地错误页面文件或远程错误目标服务器
• 基于主机的路由：可根据请求主机名进行路由选择
• 丰富的代理选项：支持X-Forwarded头、路径重写、超时控制等高级功能
• 统计集成：支持StatsD metrics输出

使用场景

• JupyterHub部署：作为JupyterHub的核心代理组件，管理多用户 Notebook 服务器路由
• 动态服务路由：需要根据运行时状态调整路由规则的多服务架构
• WebSocket代理：为WebSocket应用提供稳定的代理支持
• 开发/测试环境：快速切换不同服务实例的流量路由

使用方法

前置要求

• Node.js ≥ 6（推荐使用LTS版本）
• 若使用Docker部署，需Docker引擎≥18.06

Docker部署示例

基础启动命令

bash
docker run -d \
  --name chp \
  -p 8000:8000 \
  -p 8001:8001 \
  -e CONFIGPROXY_AUTH_TOKEN="your-secure-token" \
  docker.xuanyuan.run/jupyterhub/configurable-http-proxy \
  --default-target http://localhost:8888 \
  --log-level info

带SSL配置的启动命令

bash
docker run -d \
  --name chp-ssl \
  -p 443:8000 \
  -p 8001:8001 \
  -v /path/to/ssl:/ssl \
  -e CONFIGPROXY_AUTH_TOKEN="your-secure-token" \
  docker.xuanyuan.run/jupyterhub/configurable-http-proxy \
  --ssl-key /ssl/server.key \
  --ssl-cert /ssl/server.crt \
  --default-target https://backend-service:443 \
  --log-level debug

基本使用

启动代理

bash
configurable-http-proxy [选项]

设置默认目标

默认目标用于处理未匹配路由规则的请求：

bash
configurable-http-proxy --default-target=http://localhost:8888

命令行选项

REST API 使用

API 基础信息

• API根路径：/api/
• 认证方式：通过Authorization头传递令牌，格式：Authorization: token <CONFIGPROXY_AUTH_TOKEN>
• 默认地址：http://localhost:8001（由--api-ip和--api-port控制）

API 端点说明

认证示例

bash
export CONFIGPROXY_AUTH_TOKEN="your-secure-token"
curl -H "Authorization: token $CONFIGPROXY_AUTH_TOKEN" http://localhost:8001/api/routes

获取路由表

bash
# 获取所有路由
curl -H "Authorization: token $CONFIGPROXY_AUTH_TOKEN" http://localhost:8001/api/routes

# 获取指定时间前未活动的路由
curl -H "Authorization: token $CONFIGPROXY_AUTH_TOKEN" "http://localhost:8001/api/routes?inactive_since=2024-01-01T00:00:00Z"

添加路由

bash
# 添加路由：将/path路由到http://localhost:8002
curl -X POST \
  -H "Authorization: token $CONFIGPROXY_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target": "http://localhost:8002"}' \
  http://localhost:8001/api/routes/path

删除路由

bash
# 删除/path路由
curl -X DELETE \
  -H "Authorization: token $CONFIGPROXY_AUTH_TOKEN" \
  http://localhost:8001/api/routes/path

自定义错误页面

本地错误页面

通过--error-path指定错误页面目录，CHP会根据状态码加载对应HTML文件：

bash
configurable-http-proxy --error-path /usr/share/chp-errors

目录结构示例：

/usr/share/chp-errors/
├── 404.html   # 404错误页面
├── 503.html   # 503错误页面
└── error.html # 默认错误页面（当特定状态码文件不存在时使用）

错误目标服务器

通过--error-target指定错误处理服务器，CHP会将错误请求转发至此服务器：

bash
configurable-http-proxy --error-target http://localhost:1234

错误请求格式：GET /{状态码}?url={编码后的请求路径}，例如： GET /404?url=%2Fnotebook%2Fuser%2Ftest

基于主机的路由

启用--host-routing选项后，CHP会根据请求的主机名进行路由选择。API中通过将主机名作为路径前缀来管理路由：

bash
# 添加主机路由：将example.com路由到http://localhost:1234
curl -X POST \
  -H "Authorization: token $CONFIGPROXY_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target": "http://localhost:1234"}' \
  http://localhost:8001/api/routes/example.com

故障排除

代理无法启动

• Node.js版本问题：确保Node.js版本≥6，Ubuntu/Debian系统可能预装旧版本Node.js，建议通过https://github.com/nodesource/distributions安装最新LTS版本。

路由不生效

• 检查CONFIGPROXY_AUTH_TOKEN环境变量是否正确设置
• 通过REST API获取路由表确认路由是否存在：GET /api/routes
• 检查日志级别设置为debug，查看详细请求处理过程

SSL连接问题

• 确保证书文件路径正确且权限允许读取
• 使用--insecure选项禁用证书验证（仅测试环境使用）
• 检查目标服务器SSL配置是否支持代理请求