- 通过 Sub2API Admin Token 被动读取已保存的 OpenAI 周限快照，默认不主动请求上游额度接口。
- 按参与者合同权益维护百分比账本，并根据真实消费增量估算每 1% 周限对应的美元价值。
- 上游整数百分比、观测时间、周期边界和已采集余额永久保留；新采样按 canonical point 原子提交，历史维护先冻结不可变的本地审计计划，再零联网应用并确定性重放派生结果。
- Sub2API 0.1.179 起推荐直接在 OpenAI OAuth 渠道配置 2.5 倍 FAST 计费；Sub2Pool 默认启用 2 倍到 2.5 倍的兼容修正，并支持按模型配置有序通配规则，已保存的历史修正事实仍会永久保留并参与重放。
- 平均恒定模型保留透明的累计比例对照；时变额度模型使用混合粒子滤波估计连续容量、整数显示规则和参与者归属，并同时给出概率区间与确定性边界。
- 在参与者用户余额耗尽、建议余额变化、测算率变化或采集异常时发送邮件通知。
- 支持 SMTP 和 Resend 邮件服务。
- 提供额度总览、参与者管理、观测记录、额度统计、登录审计和使用教程。
- 管理员可为普通系统用户逐页配置只读访问权限，并精确选择其可见参与者；所有页面写操作仍仅限管理员。
- 提供由独立永久 Bearer Key 保护的业务只读 API，覆盖账号、额度、参与者、观测、模型、统计和通知数据，并内置 OpenAPI 3.1 文档。
- 记录服务端来源 IP，并可选记录浏览器通过 WebRTC 上报的辅助地址。
- 支持数据库完整导入、导出，便于服务器迁移。
- Django、Vue 3 和 SQLite 打包在一个容器中，不依赖 Redis 或单独的前端容器。
后台监控不会自动修改参与者额度；只有管理员显式点击“一键设置”才会调用写接口。使用共享订阅或相关网关前，请自行确认上游服务条款及所在地法律要求。
公开镜像地址：
ghcr.io/lingyenbird/sub2pool:latest
以下方式只下载 Compose 文件和环境变量样例，不需要克隆仓库。
mkdir -p sub2pool
cd sub2pool
curl -fsSL https://raw.githubusercontent.com/LingyeNBird/Sub2Pool/main/compose.ghcr.yaml -o compose.yaml
curl -fsSL https://raw.githubusercontent.com/LingyeNBird/Sub2Pool/main/.env.example -o .env先生成随机的 Django Secret Key：
openssl rand -hex 32编辑 .env，至少替换以下内容：
DJANGO_SECRET_KEY=粘贴刚生成的随机值
ADMIN_USERNAME=admin
ADMIN_PASSWORD=设置一个足够强的初始密码
DJANGO_ALLOWED_HOSTS=你的域名,服务器IP
WEB_PORT=8088如果通过 HTTPS 反向代理访问，还应设置：
DJANGO_CSRF_TRUSTED_ORIGINS=https://你的域名
COOKIE_SECURE=true
TRUSTED_PROXY_COUNT=1ADMIN_USERNAME 和 ADMIN_PASSWORD 只在数据库中不存在该管理员时用于首次创建。后续密码修改请使用系统设置页面。
docker compose pull
docker compose up -d
docker compose ps浏览器访问 http://服务器IP:8088。首次登录后，在“系统设置”中填写 Sub2API 地址和 Admin Token，再读取 OpenAI 上游账号及 Sub2API 用户。
cd sub2pool
docker compose pull
docker compose up -dSQLite 数据保存在 Docker 命名卷 sub2pool_sub2pool-data 中，更新或重建容器不会删除数据。迁移服务器前，建议同时使用系统设置中的“数据库迁移”功能导出完整备份。
docker compose logs -f app
docker compose down不要使用 docker compose down -v，除非确定要删除 SQLite 数据卷。
cp .env.example .env
# 编辑 .env 后启动
docker compose up -d --build本地 Compose 仍使用单容器架构：构建阶段编译 Vue 3，运行阶段由 Django/WhiteNoise 提供前端静态文件和 SPA 路由。
GitHub Pages 提供不连接后端的公开演示：
- 地址：https://lingyenbird.github.io/Sub2Pool/
- 账号：
admin - 密码：
123456
演示中的参与者、观测、统计、粒子轨迹、通知和登录记录均为确定性合成数据；所有写操作只影响当前浏览器标签页，不连接 Sub2API、数据库或邮件服务。
GitHub Actions 工作流采用“自动发布为主、手动触发兜底”的方式：
- Pull Request：运行后端测试、前端检查和多架构 Docker 构建，但不推送镜像。
- 推送到
main：验证通过后自动发布latest、上海时区的YYYYMMDD-HHmm时间标签和sha-<commit>。 - 推送
v*Git 标签：发布语义化版本标签，例如1.2.0、1.2和latest。 workflow_dispatch：可在 GitHub Actions 页面手动重新构建和发布。
例如 2026 年 8 月 6 日 19:05 发布的镜像会同时获得：
latest
20260806-1905
sha-51984cb
日常回退可以直接把 Compose 中的镜像改成时间标签；若同一分钟内连续发布，则使用不会冲突的 sha-<commit> 精确定位：
image: ghcr.io/lingyenbird/sub2pool:20260806-1905镜像同时支持 linux/amd64 和 linux/arm64，并附带 SBOM 与构建来源证明。
后端：
cd backend
uv run pytest前端：
cd frontend
corepack enable
pnpm install --frozen-lockfile
pnpm check
pnpm build图标处理脚本仅在开发阶段使用 Pillow，不会增加运行镜像依赖：
uv run --with pillow python scripts/prepare_icon.py 原图.png frontend/public/favicon.png \
--apple-touch-output frontend/public/apple-touch-icon.png该脚本只清除与画布边缘连通的近白色背景，因此会保留图标内部的白色标志，并自动裁剪到实际像素边界。
.env、SQLite 数据库、虚拟环境、构建产物和本地reference/均已从 Git 排除。- Admin Token、SMTP 密码和 Resend Key 加密存储在 SQLite 中；导出的完整数据库仍应作为敏感文件保管。
- WebRTC 地址只作为浏览器自报的辅助线索，服务端观测到的请求来源地址才是登录审计的主要依据。
- 建议部署在 HTTPS 反向代理之后，并限制管理页面的网络访问范围。
本项目以 GNU Affero General Public License v3.0 only 发布。
运行中的 Web 界面在账户菜单中提供本仓库源码链接，以满足 AGPL 网络交互场景下的源码获取要求。
本项目的前端基于 daisyUI 的 HTML Dashboard Template 开发。