Hugging Face's logo

Spaces:
chenchenaoyang
/
AI_PROJECT
Sleeping

App Files Community
AI_PROJECT / README.md
chenchenaoyang's picture
chenchenaoyang
Deploy from Codex
f395b70 verified
preview code
|
Raw
History Blame Contribute Delete
12 kB
metadata 
title: AI Project Secure Proxy
emoji: 🛡️
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
hf_oauth: true

AI_PROJECT

这个仓库现在维护两套运行形态：

  • 本地模式：Codex 账号池 + API 池 + 本地管理台
  • Hugging Face 模式：单个 Docker Space + OAuth 保护的管理台 + private dataset 持久化

核心目标：

  • 从 acc_pool/ 加载多个 Codex ChatGPT 登录态账号
  • 从 api_pool/ 加载 Claude Code / Codex 的 apiUrl + apiKey 节点池
  • 校验账号可用性并管理 refresh / cooldown / 切换
  • 提供本地和远端两种 OpenAI / Anthropic 兼容代理入口
  • 用同一套管理台维护池配置、状态和日志
  • 让 API 池节点按周期轮换，避免长期只有单个节点承接真实流量

当前目录结构 

AI_PROJECT/
├── .local-ui-data/
│   └── config-switch.json
├── acc_pool/
│   ├── _backup/
│   └── pool.json
├── api_pool/
│   ├── claude-code/
│   │   └── pool.json
│   └── codex/
│       └── pool.json
├── dist/
│   └── ui/
├── reports/
│   ├── architecture/
│   └── llm-probe/
├── src/
│   ├── README.md
│   ├── hf-space/
│   │   ├── admin-auth.mjs
│   │   ├── encrypted-pool-store.mjs
│   │   ├── encrypted-pool-store.test.mjs
│   │   ├── server.mjs
│   │   └── server.test.mjs
│   ├── proxy/
│   │   ├── api-endpoint-pool.mjs
│   │   ├── api-endpoint-pool.test.mjs
│   │   ├── codex-account-pool.mjs
│   │   └── codex-account-pool.test.mjs
│   ├── shared/
│   │   ├── pool-crypto.mjs
│   │   └── secret-sanitizer.mjs
│   ├── scripts/
│   │   ├── api-pool-proxy.mjs
│   │   ├── check-symlink-skills.sh
│   │   ├── clean-codex-home.sh
│   │   ├── codex-local-proxy.mjs
│   │   ├── migrate-codex-acc-pool.mjs
│   │   ├── probe-llm-endpoint.mjs
│   │   └── run-hf-local.sh
│   ├── ui-app/
│   └── ui-server/
├── .dockerignore
├── Dockerfile
├── package.json
├── package-lock.json
└── README.md

模块说明

  • src/proxy/

    • 账号池和 API 节点池核心逻辑
    • 负责：
      • 账号 / 节点加载
      • 预检与探活
      • refresh / cooldown / 故障切换
      • 当前活跃账号 / 节点切换
      • API 池定时切活跃节点

  • src/scripts/

    • 本地模式脚本入口
    • 包含：
      • 本地代理启动
      • API 池代理启动
      • 账号池迁移
      • LLM 探测
      • ~/.codex 保守清理

  • src/ui-server/ + src/ui-app/

    • 本地模式管理台
    • 支持池管理、代理启停、日志查看、LLM 探测和配置切换

  • src/hf-space/

    • Hugging Face 远端运行时
    • 负责：
      • /admin 管理台登录和 OAuth 中转
      • /proxy/codex-account
      • /proxy/codex-api
      • /proxy/claude-api
      • 把池数据加密后写入 private hf dataset
      • 隔离管理员会话和代理 Bearer Key

  • src/shared/

    • 本地 / 远端共用的底层能力
    • 目前包含：
      • 敏感信息打码
      • AES-GCM 池文件加密 / 解密

常用命令

用途 命令 说明
安装依赖 npm install 安装项目依赖
迁移 Codex 账号池到 pool.json npm run migrate:codex-pool 合并 acc_pool/*.json 到 acc_pool/pool.json 并备份旧文件
启动本地 Codex 账号池代理 npm run proxy:codex 启动本地 OpenAI 兼容代理
启动本地 API 池代理 npm run proxy:api-pool -- --provider=codex --pool-dir=api_pool/codex --port=8789 轮询 apiUrl + apiKey 节点池
启动本地脚本管理台 npm run ui:dev 同时启动本地 Node 后端和 React 前端
构建管理台前端 npm run ui:build 构建到 dist/ui
启动 HF 远端安全服务 npm run hf:server 运行 Hugging Face 单进程安全代理和管理台
单独测试代理逻辑 npm run test:proxy 只运行账号池 / API 池相关测试
运行全部测试 npm test 运行仓库内全部测试
探测某个 LLM 地址 npm run probe:llm -- --baseUrl=https://example.com --key=sk-xxx 输出兼容性探测结果
保守清理 ~/.codex npm run clean:codex-home 清理缓存、临时文件和 shell 快照

本地模式

本地模式下，管理台是一个减少重复手敲命令的 Web 界面。

支持的页面：

页面 能力
池管理 编辑 acc_pool/pool.json、api_pool/codex/pool.json、api_pool/claude-code/pool.json
API 池代理 启动 / 停止 Claude Code 或 Codex 的 API 池代理
Codex 账号池代理 启动 / 停止 Codex 账号池代理
LLM 探测 探测目标地址兼容性并查看报告
配置切换 管理 Codex / Claude Code 本机配置预设，并一键启用到 ~/.codex 或 ~/.claude

开发时启动：

npm run ui:dev

构建静态前端：

npm run ui:build

配置切换预设

配置切换 页面只在本地模式出现，用来管理两类本机配置：

  • Codex 配置
    • 编辑并启用 ~/.codex/auth.json
    • 编辑并启用 ~/.codex/config.toml
  • Claude Code 配置
    • 编辑并启用 ~/.claude/settings.json

行为说明：

  • 预设内容会持久化到 .local-ui-data/config-switch.json
  • 预设支持 新增 / 编辑 / 删除 / 复制 / 启用
  • 列表操作是立即保存，不需要额外点“保存”
  • 点击“启用”时会二次确认
  • “已启用”状态不是只看最后一次点击，而是会对比当前本机文件内容；如果本机文件被外部改过，会显示为“已偏离”

池文件格式

Codex 账号池推荐使用单个 acc_pool/pool.json：

[
  {
    "type": "codex",
    "disabled": false,
    "email": "user@example.com",
    "last_refresh": "2026-04-05T10:00:00.000Z",
    "tokens": {
      "access_token": "eyJ...",
      "account_id": "acc-123",
      "id_token": "eyJ...",
      "refresh_token": "rt_123"
    }
  }
]

API 池推荐使用单个 pool.json 文件：

[
  {
    "name": "codex-main-1",
    "type": "codex",
    "baseUrl": "https://example.com/v1",
    "apiKey": "sk-xxx",
    "model": "gpt-5.4",
    "disabled": false
  },
  {
    "name": "codex-backup-1",
    "type": "codex",
    "baseUrl": "https://backup.example.com/v1",
    "apiKey": "sk-yyy",
    "model": "gpt-5.4",
    "disabled": false
  }
]

Claude Code 节点只需要把 type 改成 claude-code，目录放到 api_pool/claude-code/pool.json。

API 池定时切换

API 池现在不再只在“失败时切换”。

默认行为：

  • 默认开启定时切换
  • 默认每 15 分钟 尝试把当前活跃节点切到下一个健康节点
  • 如果当前存在在途请求，则先延后，等空闲窗口再切
  • 切换前会先对候选节点做轻量探活
  • 如果没有可切换的健康节点，则保持当前活跃节点不变

这样做的目的，是让所有 API 节点都能周期性承接真实业务流量，避免某些节点长期轮不到。

本地模式可配置项：

  • enableScheduledSwitch
  • scheduledSwitchIntervalMs

Hugging Face 模式环境变量：

  • API_POOL_SCHEDULED_SWITCH_ENABLED
  • API_POOL_SCHEDULED_SWITCH_INTERVAL_MS

Hugging Face 远端管理台可配置项：

  • API 池代理 页面支持直接修改 启用定时切换 和 定时切换间隔（毫秒）
  • 保存后会把远端运行配置写入 private hf dataset 的 config/api-pool-runtime.json
  • 保存完成后会自动 reload 当前选中的远端 API 池服务
  • 这份配置独立于池条目本身，主要控制远端常驻代理的运行参数

Hugging Face 安全部署

这个仓库支持部署成单个 Docker Space。

必需的 Secrets

  • ADMIN_HF_USERNAMES
  • ADMIN_SESSION_SECRET
  • POOL_CRYPTO_KEY
  • HF_TOKEN
  • CODEX_ACCOUNT_PROXY_KEY
  • CODEX_API_PROXY_KEY
  • CLAUDE_API_PROXY_KEY

平台配置

  • 在 README frontmatter 里保持 hf_oauth: true
  • 配置 HF_DATASET_REPO=<user-or-org>/<private-dataset-name>
  • 可选：配置 HF_DATASET_BRANCH，默认 main
  • 可选：配置 POOL_STORAGE_BACKEND=hf-dataset；如果设置了 HF_DATASET_REPO，服务会默认走 dataset 后端
  • DATA_DIR 现在只作为本地缓存目录使用，默认会在其中维护 .hf-dataset-cache

可直接上线的环境变量清单

Secrets：

  • HF_TOKEN：用于读写 private Space repo 和 private dataset
  • HF_DATASET_REPO：格式为 <user-or-org>/<private-dataset-name>
  • POOL_CRYPTO_KEY：用于加密 pools/*.enc
  • ADMIN_SESSION_SECRET：管理员登录态签名密钥
  • ADMIN_HF_USERNAMES：允许进入 /admin 的 HF 用户名，多个用逗号分隔
  • CODEX_ACCOUNT_PROXY_KEY：/proxy/codex-account 的 Bearer Key
  • CODEX_API_PROXY_KEY：/proxy/codex-api 的 Bearer Key
  • CLAUDE_API_PROXY_KEY：/proxy/claude-api 的 Bearer Key

Variables：

  • POOL_STORAGE_BACKEND=hf-dataset
  • HF_DATASET_BRANCH=main
  • DATA_DIR=/tmp/hf-space-data
  • PORT=7860

可选 Variables：

  • CODEX_PROXY_UPSTREAM_BASE
  • CODEX_PROXY_REFRESH_ENDPOINT
  • CODEX_PROXY_PROBE_URL
  • CODEX_PROXY_MAX_SWITCH_ATTEMPTS
  • CODEX_PROXY_REQUEST_TIMEOUT_MS
  • CODEX_PROXY_UPSTREAM_PROXY
  • CODEX_PROXY_CLIENT_VERSION
  • API_POOL_MAX_SWITCH_ATTEMPTS
  • API_POOL_REQUEST_TIMEOUT_MS
  • API_POOL_SCHEDULED_SWITCH_ENABLED
  • API_POOL_SCHEDULED_SWITCH_INTERVAL_MS
  • API_POOL_PROXY_URL

说明：

  • OAUTH_CLIENT_ID
  • OAUTH_CLIENT_SECRET
  • OPENID_PROVIDER_URL

这些变量在 hf_oauth: true 打开后会由 Hugging Face 自动注入，不需要你手动填写。

远端路由

  • 管理台：/admin
  • Codex 账号池代理：/proxy/codex-account
  • Codex API 池代理：/proxy/codex-api
  • Claude API 池代理：/proxy/claude-api

远端模式注意事项

  • 不要把 acc_pool/、api_pool/、.local-ui-data/ 上传到 Space 仓库
  • 池数据会加密后写入 private hf dataset 里的 pools/*.enc
  • 代理 Bearer Key 和管理员会话是两套独立鉴权，不能混用
  • 未登录访问 /admin 时，会先显示一个登录中转页；请在新标签页完成 OAuth
  • 如果 HF_TOKEN 或 HF_DATASET_REPO 缺失，远端池管理会自动退化为只读
  • API 池的定时切换在远端模式下同样默认开启
  • 远端模式下可以在管理台直接调整 API 池定时切换开关和间隔；配置会持久化到 private hf dataset 的 config/api-pool-runtime.json

远端模式推荐使用流程

  1. 打开 https://<space>.hf.space/admin
  2. 在登录中转页点击“在新标签页登录”
  3. 登录后进入池管理
  4. 导入账号池或 API 池 JSON
  5. 如需调整远端 API 池轮换策略，进入 API 池代理 页面修改定时切换开关或间隔，并点击“保存并重载当前服务”
  6. 如果只改了池文件内容，再点击 Reload 配置
  7. 再把本地客户端指向对应 /proxy/* 路由

本地客户端固定接入形态

  • Codex 账号池：https://<space>.hf.space/proxy/codex-account
  • Codex API 池：https://<space>.hf.space/proxy/codex-api
  • Claude API 池：https://<space>.hf.space/proxy/claude-api

接手建议

如果你是第一次接手这个仓库，建议阅读顺序：

  1. 先看本文件，了解仓库的本地 / 远端两种运行方式
  2. 再看 src/README.md，了解脚本入口和池格式
  3. 看 server.mjs，了解远端安全代理和管理台入口
  4. 最后看 codex-account-pool.mjs，理解账号池和切换逻辑