好，我帮你直接整理成一份可以直接放仓库用的 README（带目录 + 文内跳转 + 架构图），结构已经优化过，适合长期维护 👇
📄 README.md（完整版）
# 📚 Token Pool & Codex 调试体系
---
## 📖 目录
- [一、核心结论](#核心结论)
- [二、系统架构](#系统架构)
- [三、本地 vs 云端](#本地-vs-云端)
- [四、端口说明](#端口说明)
- [五、Nginx 转发机制](#nginx-转发机制)
- [六、Codex 本地调试本质](#codex-本地调试本质)
- [七、常见问题（重要）](#常见问题重要)
- [八、调试最佳实践](#调试最佳实践)
- [九、总结](#总结)
---
## 🧠 核心结论
```text
本地端口 ≠ 云端端口
它们是两套完全独立的运行实例👉 不是一个服务两个入口
👉 而是两个环境：
-
本地（开发环境）
-
云端（生产环境）
🏗 系统架构
[Codex 本地 Agent]
│
│ HTTP（base_url 可切换）
▼
[Token Pool（本地 or 云端）]
│
▼
[上游模型]🧩 本地 vs 云端
🟢 本地 Token Pool（开发）
http://127.0.0.1:3100 → master
http://127.0.0.1:3301 → worker（API）特点：
-
本机运行
-
可调试 / 可修改代码
-
会 crash / restart
🔵 云端 Token Pool（生产）
https://key.tengokukk.com/openai/v1特点：
-
部署在服务器（170.x.x.x）
-
nginx + systemd 管理
-
稳定运行
🔥 为什么会“混乱”
Codex → 云端
你调试 → 本地👉 结果：
-
本地挂了但还能用
-
修了但没效果
🧭 如何判断当前用的是哪一套
✅ 方法 1：看 base_url
https://key.tengokukk.com → 云端
http://127.0.0.1:3301 → 本地✅ 方法 2：接口测试
curl http://127.0.0.1:3301/openai/v1/models
curl https://key.tengokukk.com/openai/v1/models✅ 方法 3：关闭本地
kill node👉 如果还能用 → 说明在用云端
⚙️ 端口说明
| 端口 | 用途 |
|---|---|
| 127.0.0.1 | 本机回环地址 |
| 3100 | Token Pool master |
| 3301 | Token Pool worker |
| 80 | HTTP |
| 443 | HTTPS |
🌐 Nginx 转发机制
用户请求
↓
https://key.tengokukk.com
↓
Nginx (443)
↓
Token Pool (Node)
↓
Provider👉 本质：
Nginx = 反向代理🧠 Codex 本地调试本质
✔ Codex 本地 Agent
-
本地运行
-
可执行命令（shell / 文件）
-
管理上下文
-
不属于 Token Pool
✔ Token Pool
-
只是 API 网关
-
不负责本地执行
🧩 核心关系
Codex ≠ Token Pool
Codex 使用 Token Pool⚠️ 常见问题（重要）
❌ 错误用法
本地 debug + 云端调用👉 会导致：
-
判断错误
-
修复无效
-
排查困难
✅ 正确方式
🟢 方式 A（推荐）
Codex → 本地 Token Pool🔵 方式 B
Codex → 云端 Token Pool🧭 调试最佳实践
先确认环境（本地 / 云端）
再看端口（3100 / 3301）
再看请求路径
最后看日志🎯 总结
你看到两个端口，不是一个系统有两个入口
而是你同时在使用“本地实例”和“云端实例”🚀 扩展方向
-
自动环境切换（local / prod）
-
Codex + Token Pool 自动调度
-
crash 根因分析系统
-
provider 智能优化
---
# ✅ 这个版本已经帮你做好了
✔ 目录
✔ 文内跳转（全部可点）
✔ 架构图（ASCII）
✔ 层级清晰（适合团队）
✔ 可直接放 GitHub
---
# 🚀 如果你要再进阶一点
我可以帮你再升级一版：
👉 加 **Mermaid 架构图（更专业）**
👉 自动生成 **API 调用流程图**
👉 或做一个 **开发 / 生产切换指南**
直接说 👍
很好，这三个问题是从“本地开发”到“能给别人用”的关键，我给你一套从原理 → 实现 → 实战的完整讲解👇
🧠 一、为什么别人访问不了你本地？
🎯 核心原因
127.0.0.1 = 只在你自己电脑内部有效🧩 举个真实例子
你访问：
http://127.0.0.1:3301👉 实际发生：
请求 → 直接回到你自己电脑 → 不走互联网❌ 别人访问会发生什么？
别人访问：
http://你的IP:3301但：
👉 你的电脑通常：
-
没开放公网端口
-
在路由器/NAT后面
-
被防火墙拦住
🔥 所以结论
本地服务默认是“私有的”，只能自己访问🌐 二、怎么把本地服务变成公网？
有三种主流方式👇
🟢 方案 1：内网穿透（最简单）
👉 推荐新手用
常见工具：
-
ngrok
-
frp
-
cloudflare tunnel
🎯 原理
你电脑 → 连接一个公网服务器 → 生成一个公网地址🧪 示例（ngrok）
ngrok http 3301输出：
https://abc123.ngrok.io👉 现在别人访问：
https://abc123.ngrok.io👉 就能访问你本地服务了
🧠 本质
你主动“打洞”连接外网服务器🔵 方案 2：服务器中转（生产常用）
👉 你现在用的就是这个
架构
公网用户
↓
Nginx（服务器）
↓
Token Pool（服务器）👉 本地不参与
优点
-
稳定
-
可控
-
安全
🟡 方案 3：直接开放端口（不推荐）
需要：
-
公网 IP
-
路由器端口转发
-
关闭防火墙限制
风险：
❌ 非常不安全
❌ 容易被扫描攻击🧠 推荐结论
开发 → 内网穿透
生产 → 云服务器 + nginx⚙️ 三、nginx / 端口转发怎么打通？
🧱 nginx 是干嘛的？
Nginx = 流量入口（反向代理）🧩 基本结构
用户请求
↓
https://你的域名
↓
Nginx
↓
Node服务（127.0.0.1:3301）✍️ 最简单 nginx 配置
server {
listen 80;
server_name yourdomain.com;
location / {
proxy_pass http://127.0.0.1:3301;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}🔥 如果是 HTTPS（你现在的）
server {
listen 443 ssl;
server_name key.tengokukk.com;
ssl_certificate /path/fullchain.pem;
ssl_certificate_key /path/privkey.pem;
location / {
proxy_pass http://127.0.0.1:3301;
}
}🧠 nginx 做了什么？
公网请求 → 转发到本地 Node 服务🔌 四、端口转发（补充理解）
📌 路由器端口转发
公网IP:80
↓
路由器
↓
你的电脑:3301👉 但这个：
❌ 家用网络复杂
❌ IP 会变
❌ 不稳定
🧠 五、你当前项目的真实结构（结合你）
🔵 云端（你现在用的）
https://key.tengokukk.com
↓
Nginx (443)
↓
127.0.0.1:3301（服务器上的 Node）🟢 本地（你调试）
http://127.0.0.1:3301👉 两者完全独立
🎯 六、最实用总结
❓ 为什么别人访问不了你本地？
因为 127.0.0.1 只代表“他自己”❓ 怎么变公网？
✔ 内网穿透（开发）
✔ 云服务器（生产）❓ nginx 在干嘛？
把公网请求转发给本地服务🧠 最后一张总图（建议记住）
开发模式：
你 → 127.0.0.1:3301
内网穿透：
你 → ngrok → 你电脑
生产模式：
用户 → nginx → Node服务🚀 如果你下一步想更狠一点
我可以帮你：
👉 手把手搭一个：
-
本地 Token Pool → ngrok 公网访问
-
或你自己的 nginx + 域名部署
甚至：
👉 把你现在这个 Token Pool 做成真正 SaaS 👍
这个问题问得很好，而且是你现在整个系统（本地 → 云端 → nginx）里最关键的一块基础认知。
我给你讲清楚，不讲虚的👇
🧠 一句话理解
域名 = 给服务器起的“好记的名字”👉 用来代替难记的 IP 地址
🧩 举个最直观的例子
没有域名：
https://170.12.34.56有域名：
https://key.tengokukk.com👉 明显：
-
域名 ✔ 好记
-
IP ❌ 很难记
🔥 域名真正的作用（不止是好看）
① 📛 人类可读（最基础）
IP → 给机器看的
域名 → 给人看的② 🌐 通过 DNS 找到服务器
当你访问：
https://key.tengokukk.com实际过程：
域名 → DNS 查询 → IP 地址 → 连接服务器👉 就像：
通讯录名字 → 查电话 → 打过去③ 🔒 支持 HTTPS（非常重要）
没有域名：
❌ 很难用 HTTPS
❌ 浏览器会警告
有域名：
✔ 可以申请 SSL 证书（https）
✔ 数据加密
✔ 浏览器信任
👉 你现在这个：
https://key.tengokukk.com就是：
域名 + SSL = 安全访问④ 🚪 配合 nginx 做“统一入口”
用户 → 域名 → nginx → Node服务👉 作用：
-
不暴露真实端口（3301）
-
可以转发多个服务
-
可以做权限控制
⑤ 🧭 支持多服务分发（高级）
同一个服务器：
api.xxx.com → API服务
admin.xxx.com → 后台
key.xxx.com → Token Pool👉 一个 IP → 多个系统
⑥ 📈 可扩展 / 可迁移
你换服务器：
旧IP → 新IP👉 只需要改：
域名解析（DNS）用户完全无感
🧠 回到你现在这个项目
🔵 云端访问
https://key.tengokukk.com/openai/v1👉 实际发生：
域名 → IP（170.x.x.x）
→ nginx
→ 127.0.0.1:3301
→ Token Pool🟢 本地访问
http://127.0.0.1:3301👉 没有域名：
-
只能你自己用
-
不能 HTTPS
-
不能公网访问
🧨 如果没有域名会怎样？
❌ 只能用 IP
❌ 不方便
❌ HTTPS 很麻烦
❌ 不专业
❌ 无法做多服务分发🎯 最关键一句总结
域名 = 用户访问入口 + 安全基础 + 系统扩展能力🧠 再给你一个工程级理解（重要）
你现在的系统其实是：
域名（key.tengokukk.com）
↓
Nginx（入口网关）
↓
Token Pool（3301）
↓
Provider👉 域名就是：
👉 整个系统的“入口门牌号”
🚀 如果你下一步想继续深入
我可以帮你搞这些👇
👉 域名是怎么注册的（阿里云 / Cloudflare）
👉 DNS 是怎么配置的（A记录 / CNAME）
👉 怎么给你这个项目绑定域名
👉 怎么自动申请 HTTPS（Let’s Encrypt）
甚至：
👉 手把手帮你把本地 Token Pool 变成一个公网域名服务 👍
