appstore/apps/sub2api

Sub2API

Sub2API 是一个面向订阅转换与统一接口访问场景的轻量服务，适合在 1Panel 中作为独立应用部署，为客户端或上游系统提供稳定的订阅处理入口。

应用简介

该应用提供 Web 访问入口，并支持自动初始化、管理员账户设置、日志级别控制、JWT/TOTP 安全配置，以及基于 PostgreSQL 与 Redis 的持久化与缓存能力。当前 1Panel 适配版本采用“应用本体 + 商店依赖”的方式交付，便于直接复用面板内已有的数据库与缓存服务。

功能亮点

• 支持订阅转换与 API 化访问，方便统一接入与后续集成
• 支持 PostgreSQL + Redis 组合依赖，适合长期运行
• 支持管理员邮箱、管理员密码、JWT 密钥、TOTP 加密密钥等初始化参数
• 支持日志级别与安全 URL 白名单开关，便于按环境调整
• 支持数据目录挂载，方便备份、迁移与持久化管理

持久化目录

适配默认使用相对目录持久化应用数据：

• ./data → /app/data

其中 /app/data 会保存应用运行数据、自动生成的 config.yaml、日志以及部分缓存内容。上游入口脚本会在启动时确保该目录可写。数据库和 Redis 的数据由对应的 1Panel 依赖应用自行管理。

安装说明

安装时需要在 1Panel 表单中补齐以下关键信息：

• PostgreSQL 服务实例
• Redis 服务实例
• 管理员邮箱
• 访问端口
• 数据目录
• 安全参数：JWT_SECRET、TOTP_ENCRYPTION_KEY、ADMIN_PASSWORD

其中数据库与缓存服务由 1Panel 商店依赖注入：

• PostgreSQL：用于应用数据持久化
• Redis：用于缓存与运行时状态

若面板中已经安装对应服务，直接在安装表单中选择实例与 Service 即可。

默认配置

• 访问端口：8080
• 容器内部端口：8080
• 默认数据目录：./data
• 容器内数据目录：/app/data
• 默认时区：Asia/Shanghai
• 默认日志级别：info

使用建议

• 首次安装时补全管理员邮箱，建议同时设置管理员密码
• 生产环境建议显式配置 JWT_SECRET 与 TOTP_ENCRYPTION_KEY
• 若启用 URL 安全白名单，请提前确认业务访问范围
• 如需代理更新源，可按需填写 UPDATE_PROXY_URL

安装后检查

1. 打开 http://<服务器IP>:<访问端口> 确认页面可访问。
2. 检查数据库与 Redis 连接是否正常。
3. 确认数据目录已正确挂载并具备写入权限。
4. 若使用初始化管理员账户，确认可正常登录后台。

反向代理说明

如果你在 Nginx 后面反代 Sub2API，并且需要兼容 Codex CLI 等依赖下划线请求头的客户端，请在 Nginx 的 http 块中开启：

underscores_in_headers on;

这是上游 README 明确提到的要求，否则某些带下划线的头部可能会被 Nginx 丢弃，影响会话粘性与部分 CLI 场景。

备注

• 本适配默认启用 AUTO_SETUP=true
• 默认时区为 Asia/Shanghai
• 生命周期脚本只会初始化应用自身的 ./data 目录，不会创建数据库或 Redis 的本地目录，因为这两者由 1Panel 依赖应用托管
• 如需更细的运行参数，可参考 latest/.env.sample 和上游文档继续扩展