feat: add standalone CLI project

2026-03-19 07:36:14 +08:00
commit 26b238ec25
16 changed files with 6103 additions and 0 deletions
--- a/CONFIG_GUIDE.md
+++ b/CONFIG_GUIDE.md
@@ -0,0 +1,451 @@
+# Standalone CLI 配置说明
+
+这个文件用来解释 `/root/standalone_cli/data/sync_config.json` 里常用字段该怎么填。
+
+注意：`sync_config.json` 是 JSON，不能直接写注释，所以说明单独放在这里。
+
+## 最少需要关心的字段
+
+如果你只是先跑起来，优先看这几项：
+
+- `proxy`
+- `mail_providers`
+- `mail_provider_configs`
+- `cpa_base_url`
+- `cpa_token`
+- `base_url`
+- `bearer_token` 或 `email` + `password`
+
+## 字段说明
+
+### 1. `proxy`
+
+作用：注册 OpenAI 时使用的固定代理。
+
+常见填写示例：
+
+```json
+"proxy": "http://127.0.0.1:7897"
+```
+
+如果你本地跑了 Clash / Mihomo / sing-box，一般就是本机 HTTP 代理端口。
+
+如果你不想走固定代理，也可以留空：
+
+```json
+"proxy": ""
+```
+
+## 2. `auto_register`
+
+作用：用于池维护场景下，是否允许在账号不足时自动触发注册。
+
+一般先保持：
+
+```json
+"auto_register": false
+```
+
+## 3. `mail_providers`
+
+作用：启用哪些邮箱提供商。
+
+当前可选值通常包括：
+
+- `mailtm`
+- `duckmail`
+- `moemail`
+- `cloudflare_temp_email`
+
+示例：只用 `mailtm`
+
+```json
+"mail_providers": ["mailtm"]
+```
+
+示例：多个提供商轮询
+
+```json
+"mail_providers": ["mailtm", "duckmail", "moemail"]
+```
+
+## 4. `mail_provider_configs`
+
+作用：为每个邮箱提供商填写自己的连接参数。
+
+### `mailtm`
+
+通常默认即可：
+
+```json
+"mailtm": {
+  "api_base": "https://api.mail.tm"
+}
+```
+
+### `duckmail`
+
+如果你要用 DuckMail：
+
+```json
+"duckmail": {
+  "api_base": "https://api.duckmail.sbs"
+}
+```
+
+### `moemail`
+
+如果你有 MoeMail 服务：
+
+```json
+"moemail": {
+  "api_base": "https://your-moemail.example.com",
+  "api_key": "your_moemail_api_key"
+}
+```
+
+### `cloudflare_temp_email`
+
+如果你自己有 Cloudflare Worker 邮箱接口：
+
+```json
+"cloudflare_temp_email": {
+  "api_base": "https://your-worker.example.com",
+  "admin_password": "your_admin_password",
+  "domain": "example.com"
+}
+```
+
+这里几项的含义：
+
+- `api_base`：你的 Worker 接口地址
+- `admin_password`：你的 Worker 后端管理密码
+- `domain`：临时邮箱生成时使用的域名后缀
+
+## 5. `mail_strategy`
+
+作用：多个邮箱提供商启用时的调度策略。
+
+可选值：
+
+- `round_robin`：轮询，推荐默认
+- `random`：随机
+- `failover`：优先一个，失败再切下一个
+
+推荐：
+
+```json
+"mail_strategy": "round_robin"
+```
+
+## 6. `base_url`
+
+作用：Sub2Api 平台地址。
+
+示例：
+
+```json
+"base_url": "https://sub2api.example.com"
+```
+
+要求：
+
+- 必须带 `http://` 或 `https://`
+- 不能写成纯域名裸字符串
+
+错误示例：
+
+```json
+"base_url": "sub2api.example.com"
+```
+
+正确示例：
+
+```json
+"base_url": "https://sub2api.example.com"
+```
+
+## 7. `bearer_token`
+
+作用：Sub2Api 管理员 Bearer Token。
+
+如果你已经知道管理员 Token，可以直接填：
+
+```json
+"bearer_token": "your_sub2api_bearer_token"
+```
+
+## 8. `email` 和 `password`
+
+作用：如果你不想手动填 `bearer_token`，可以填 Sub2Api 管理员账号密码，让 CLI 去登录并获取 token。
+
+示例：
+
+```json
+"email": "admin@example.com",
+"password": "your_password"
+```
+
+通常两种方式二选一：
+
+- 方式 A：填 `bearer_token`
+- 方式 B：填 `email` + `password`
+
+## 9. `account_name`
+
+作用：导入或展示时默认账号名称前缀。
+
+一般默认就行：
+
+```json
+"account_name": "AutoReg"
+```
+
+## 10. `auto_sync`
+
+作用：注册成功后，是否自动同步到 Sub2Api。
+
+如果你希望注册后自动推送到 Sub2Api：
+
+```json
+"auto_sync": true
+```
+
+否则：
+
+```json
+"auto_sync": false
+```
+
+## 11. `cpa_base_url`
+
+作用：CPA 平台地址。
+
+示例：
+
+```json
+"cpa_base_url": "https://cpa.example.com"
+```
+
+要求同样是：
+
+- 必须带 `http://` 或 `https://`
+
+## 12. `cpa_token`
+
+作用：CPA 平台认证 token。
+
+示例：
+
+```json
+"cpa_token": "your_cpa_token"
+```
+
+## 13. `min_candidates`
+
+作用：CPA 池健康阈值，低于这个候选数量就认为池子偏少。
+
+例如：
+
+```json
+"min_candidates": 1000
+```
+
+如果你的使用规模不大，也可以调低，比如：
+
+```json
+"min_candidates": 100
+```
+
+## 14. `used_percent_threshold`
+
+作用：CPA 池已使用比例的告警阈值。
+
+常见值：
+
+```json
+"used_percent_threshold": 95
+```
+
+## 15. `auto_maintain`
+
+作用：是否自动执行 CPA 池维护。
+
+```json
+"auto_maintain": true
+```
+
+如果你只想手动维护，也可以关掉：
+
+```json
+"auto_maintain": false
+```
+
+## 16. `maintain_interval_minutes`
+
+作用：自动维护的时间间隔，单位分钟。
+
+```json
+"maintain_interval_minutes": 30
+```
+
+## 17. `sub2api_min_candidates`
+
+作用：Sub2Api 池健康阈值。
+
+```json
+"sub2api_min_candidates": 200
+```
+
+## 18. `sub2api_auto_maintain`
+
+作用：是否自动执行 Sub2Api 池维护。
+
+```json
+"sub2api_auto_maintain": false
+```
+
+## 19. `sub2api_maintain_actions`
+
+作用：Sub2Api 维护时具体做哪些动作。
+
+默认：
+
+```json
+"sub2api_maintain_actions": {
+  "refresh_abnormal_accounts": true,
+  "delete_abnormal_accounts": true,
+  "dedupe_duplicate_accounts": true
+}
+```
+
+这三项分别表示：
+
+- `refresh_abnormal_accounts`：对异常账号做刷新/测活
+- `delete_abnormal_accounts`：对仍异常的账号执行删除
+- `dedupe_duplicate_accounts`：清理重复账号
+
+## 20. `upload_mode`
+
+作用：上传/同步策略。
+
+一般保留默认：
+
+```json
+"upload_mode": "snapshot"
+```
+
+## 21. `proxy_pool_enabled`
+
+作用：是否启用代理池，而不是固定 `proxy`。
+
+如果你没有代理池，建议保持：
+
+```json
+"proxy_pool_enabled": false
+```
+
+## 22. `proxy_pool_*`
+
+这些字段用于代理池：
+
+- `proxy_pool_api_url`
+- `proxy_pool_auth_mode`
+- `proxy_pool_api_key`
+- `proxy_pool_count`
+- `proxy_pool_country`
+
+示例：
+
+```json
+"proxy_pool_enabled": true,
+"proxy_pool_api_url": "https://your-proxy-pool.example.com/api/fetch",
+"proxy_pool_auth_mode": "header",
+"proxy_pool_api_key": "your_proxy_pool_api_key",
+"proxy_pool_count": 1,
+"proxy_pool_country": "US"
+```
+
+说明：
+
+- `proxy_pool_auth_mode` 一般是 `header` 或 `query`
+- `proxy_pool_country` 常见填 `US`
+
+## 推荐的最小可用配置
+
+如果你要先跑注册，再决定同步哪个平台，可以先这样：
+
+```json
+{
+  "proxy": "http://127.0.0.1:7897",
+  "auto_register": false,
+  "mail_providers": ["mailtm"],
+  "mail_provider_configs": {
+    "mailtm": {
+      "api_base": "https://api.mail.tm"
+    }
+  },
+  "mail_strategy": "round_robin",
+  "multithread": false,
+  "thread_count": 3,
+  "base_url": "",
+  "bearer_token": "",
+  "email": "",
+  "password": "",
+  "account_name": "AutoReg",
+  "auto_sync": false,
+  "sub2api_min_candidates": 200,
+  "sub2api_auto_maintain": false,
+  "sub2api_maintain_interval_minutes": 30,
+  "sub2api_maintain_actions": {
+    "refresh_abnormal_accounts": true,
+    "delete_abnormal_accounts": true,
+    "dedupe_duplicate_accounts": true
+  },
+  "cpa_base_url": "",
+  "cpa_token": "",
+  "min_candidates": 1000,
+  "used_percent_threshold": 95,
+  "auto_maintain": false,
+  "maintain_interval_minutes": 30,
+  "upload_mode": "snapshot",
+  "proxy_pool_enabled": false,
+  "proxy_pool_api_url": "https://zenproxy.top/api/fetch",
+  "proxy_pool_auth_mode": "header",
+  "proxy_pool_api_key": "",
+  "proxy_pool_count": 1,
+  "proxy_pool_country": "US"
+}
+```
+
+## 如果你不知道怎么填
+
+最常见的组合是：
+
+- 只注册，不同步平台：
+  - 填 `proxy`
+  - 填邮箱提供商配置
+  - `auto_sync = false`
+  - `cpa_base_url` / `base_url` 可以先留空
+- 注册并同步到 Sub2Api：
+  - 填 `proxy`
+  - 填邮箱提供商配置
+  - 填 `base_url`
+  - 填 `bearer_token` 或 `email + password`
+  - `auto_sync = true`
+- 注册并维护 CPA：
+  - 填 `proxy`
+  - 填邮箱提供商配置
+  - 填 `cpa_base_url`
+  - 填 `cpa_token`
+
+## 建议命令
+
+配置好之后常用命令是：
+
+```bash
+python3 /root/standalone_cli/run.py --json config show
+python3 /root/standalone_cli/run.py register --once
+python3 /root/standalone_cli/run.py cpa status
+python3 /root/standalone_cli/run.py sub2api status
+```