Delete DEPLOY.md
Browse files
DEPLOY.md
DELETED
|
@@ -1,57 +0,0 @@
|
|
| 1 |
-
# 部署说明
|
| 2 |
-
|
| 3 |
-
## 平台资格
|
| 4 |
-
Hugging Face 当前文档规定：新建 Docker SDK Space 需要付费计划（个人 PRO，组织 Team/Enterprise）；CPU Basic 运行硬件本身不计时费。若你的账号只有免费计划，无法保证创建此 Docker Space。已有符合资格的 Docker Space 可以直接部署。
|
| 5 |
-
免费 CPU Basic 仍可能因闲置休眠；外部轮询不是官方常驻运行保障。
|
| 6 |
-
|
| 7 |
-
## 部署
|
| 8 |
-
1. 创建 Docker SDK Space，将本目录所有非忽略文件提交到 Space 仓库根目录；README.md 中 app_port 为 7860。
|
| 9 |
-
2. 在 Space Settings 添加 Secrets：QQBOT_APP_ID、QQBOT_APP_SECRET、CODEX_API_KEY、JUPYTER_TOKEN（长随机值）。添加 Variables：QQ_ALLOWED_OPENIDS、CODEX_BASE_URL、CODEX_MODEL。密钥不要提交到仓库。
|
| 10 |
-
3. CODEX_BASE_URL 应是兼容 OpenAI Responses API 的供应商地址；CODEX_MODEL 是该供应商真实模型 ID。当前 Codex 不支持将 wire_api 设为 chat；仅 Chat Completions 的供应商不可直接使用。
|
| 11 |
-
4. 构建完成后访问 Space 的 .hf.space 地址，输入 JUPYTER_TOKEN 登录 JupyterLab。QQ 机器人在同一容器自动启动；私聊发送 /status 验证。
|
| 12 |
-
5. 会话写入 data/history.json 并在每次启动时重新置空；容器文件层及 workspace 在重建时可能丢失，不要存放长期需要的文件。
|
| 13 |
-
|
| 14 |
-
## UptimeRobot
|
| 15 |
-
Space 上线并取得真实公开域名后，在 UptimeRobot 选择 HTTP(s) monitor，URL 填 https://你的实际子域名.hf.space/health，免费计划通常每 5 分钟检查一次。该端点仅在 QQ 进程与 JupyterLab 均存活时返回 HTTP 200 和 ok。
|
| 16 |
-
不要选 Heartbeat/Cron 类型：它要求应用向 UptimeRobot 主动发送请求，而这里是外部服务请求 Space。
|
| 17 |
-
需要实际 Space URL 及 UptimeRobot 登录/授权才能创建远程监控；这里只提供可部署的端点和配置说明。外部心跳不能保证避免平台强制休眠或重启。
|
| 18 |
-
|
| 19 |
-
## 安全
|
| 20 |
-
## QQ 临时调用设置
|
| 21 |
-
发送 `/switch gpt-6-sol` 可临时切换当前会话模型，发送 `/effort low` 可切换推理深度；支持 low、medium、high、xhigh、max、ultra。机器人会明确回复成功或参数错误。状态只保存在机器人内存中，不修改环境变量和 Codex 配置，不需要重建 Space；重启后恢复 CODEX_MODEL 和 CODEX_REASONING_EFFORT 默认值。私聊按会话独立，群聊内共享；切换不影响正在运行的任务，仅作用于下一次提交。`/status` 显示下一次调用配置；`/reset` 只清历史，不撤销切换。成功提示仅表示覆盖值已保存，不保证第三方供应商支持该模型或深度。
|
| 22 |
-
|
| 23 |
-
公网 /health 不暴露令牌或聊天内容。JupyterLab 本身必须用 JUPYTER_TOKEN 保护；有访问权者可读取容器内运行时环境变量，请勿分享令牌。不要上传原项目的 .env、data 或 node_modules。原 qq-codex-bridge 未修改。
|
| 24 |
-
|
| 25 |
-
## Codex CLI 与 JupyterLab
|
| 26 |
-
容器内全局安装 Codex CLI，JupyterLab 的 Terminal 中可直接执行 codex、codex --help 或 codex exec。QQ 机器人调用的也是同一份 CLI 和同一容器用户环境。CODEX_WORKDIR 默认是 /home/node/app/workspace，JupyterLab 根目录与它一致。
|
| 27 |
-
每次容器启动会清空 workspace 顶层内容、data/history.json、日志和临时 Codex 输出文件；因此重启后聊天上下文与工作文件都会丢弃并重新创建。不要将 CODEX_WORKDIR 指向挂载卷或持久化目录。
|
| 28 |
-
|
| 29 |
-
|
| 30 |
-
## 联网检索与文件生成
|
| 31 |
-
镜像安装了 curl、Python requests/BeautifulSoup，以及 python-pptx、openpyxl、python-docx、reportlab。Codex CLI 在 Docker 容器边界内采用 danger-full-access（不创建 bwrap namespace），并在临时 CODEX_HOME 中加载 skills/web-research、skills/pptx、skills/xlsx、skills/docx。这些是容器内的 Codex 技能和 Python 库，不是桌面 Codex 应用专用插件；后者不能直接搬到 Space。联网新闻请求会抓取公开来源；PPT、Excel、Word 请求会在 workspace 生成真实文件，QQ 桥接会自动回传支持的附件。若供应商 API 本身不允许工具调用，联网仍可通过容器的 curl/Python 完成。
|
| 32 |
-
|
| 33 |
-
第三方 Responses 网关不一定支持原生 web_search 工具；默认为通过 Codex 执行 curl/Python 做网页检索。若供应商明确支持 Responses 的 web_search 工具，可在 Space Variables 中设置 CODEX_ENABLE_WEB_SEARCH=true 启用 Codex --search；否则保持默认 false。此项不能凭配置强制第三方网关提供 web_search。
|
| 34 |
-
在 JupyterLab Terminal 验证：`echo $CODEX_HOME`、`codex --version`、`python -c "import pptx, openpyxl, docx, requests"`、`curl -IL https://www.wikipedia.org`。生成测试文件后应位于 `/home/node/app/workspace`，QQ 会自动回传新生成的 pptx/xlsx/docx 文件。若网络请求失败，检查 Space 出站网络与目标网站限制。
|
| 35 |
-
|
| 36 |
-
|
| 37 |
-
## bwrap namespace 错误及安全边界
|
| 38 |
-
Hugging Face Space 的 Docker 运行环境可能禁止非特权 user namespace。Codex 的 `workspace-write` 沙���依赖 bwrap，会报 `No permissions to create a new namespace`，导致所有工具命令执行失败，即使模型 API 和 curl 本身可访问。QQ 桥接现固定调用 `codex exec -s danger-full-access`，不再启动 bwrap；Jupyter Terminal 的 Codex 配置也默认 `sandbox_mode = "danger-full-access"`。原先 Space Settings 中的 `CODEX_SANDBOX=workspace-write` 可删除，桥接不会再读取它。**需要重新上传并重新构建 Space**；旧镜像仍会使用旧代码。
|
| 39 |
-
|
| 40 |
-
这仅依赖 Docker/Space 容器的隔离，不等同于 Codex 的文件系统沙箱。QQ 白名单用户可以让模型读取容器内任何可读文件、执行命令、访问运行时环境变量和外网。严格保护 QQ_ALLOWED_OPENIDS 与 JUPYTER_TOKEN；不要把其他生产密钥放入同一 Space。如不能接受该风险，请改用支持非特权 user namespace 的宿主环境，或等待平台支持相应沙箱能力。
|
| 41 |
-
|
| 42 |
-
|
| 43 |
-
## 长任务无回复与 Jupyter 拒绝访问排查（本版）
|
| 44 |
-
旧版 `codex exec --json` 的 stdout 没有消费，输出事件积累后管道会满，使子进程卡住。新版持续消费 stdout、记录退出状态；默认 CODEX_TIMEOUT_MS=900000（15 分钟），超时后强制终止进程。若 Space Settings 已配置旧值 CODEX_TIMEOUT_MS=300000，旧值仍优先，请手动改为 900000 或 1200000（20 分钟）。QQ 每 3 分钟发送进度；发送 `/status` 可查询当前任务运行时间，不会排在任务后面。
|
| 45 |
-
|
| 46 |
-
启动日志在 Space 的运行日志中输出，并同时写在容器临时目录：`/home/node/app/data/startup.log`、`jupyter.log`、`bridge.log`、`nginx.log`。启动顺序改为 Jupyter → HTTP 代理 → QQ 机器人；QQ 配置缺失或机器人退出时不会一并杀死 Jupyter 界面。`/health` 现在只确认 Jupyter 可连接，不代表 QQ 机器人已登录；通过 QQ `/status` 检查机器人。
|
| 47 |
-
|
| 48 |
-
JupyterLab 必须设置 Space Secret `JUPYTER_TOKEN`，打开实际 Space App 地址的 `/lab`，在登录页面输入该 token。若显示 Hugging Face 的 403/拒绝访问页面而不是 Jupyter 登录页，检查 Space 是否 Private、账号是否有该 Space 访问权、是否打开了实际 App 地址；这类平台访问控制不是容器内 token 可以解决的。若 `/health` 为 200、`/lab` 跳转到 `/login`，说明容器与代理已工作，需检查 token/浏览器 Cookie。不要将 token 作为 URL 参数公开分享。
|
| 49 |
-
|
| 50 |
-
若仍无法进入界面，请从 Hugging Face Space 的 Runtime logs 复制 `jupyter.log`/`nginx` 对应错误、以及浏览器网络请求的 HTTP 状态码（不要包含 token 或 API key）。
|
| 51 |
-
|
| 52 |
-
QQ 白名单用户还可以发送 `/diag` 获取脱敏后的最近 bridge/startup/jupyter 日志；若机器人仍在线，优先用 `/status` 和 `/diag` 排查，无须进入 Jupyter Terminal。不要把诊断消息转发给其他人。容器的 Jupyter 与 QQ 日志默认保存在临时 data 目录；启动崩溃时会将脱敏后的最后几行写入 Space Runtime logs。
|
| 53 |
-
|
| 54 |
-
## UptimeRobot 成功请求记录
|
| 55 |
-
每次 `/health` 同时确认 Jupyter 可连接并返回 HTTP 200 后，服务会在 `/home/node/app/data/uptime-heartbeat.log` 追加一个 `.` 字符；启动时删除旧文件并重建为空文件。查看该文件的字符数即可判断成功到达的健康请求次数，例如 `wc -c data/uptime-heartbeat.log`。失败的请求、404 和 Jupyter 未启动时不会追加字符。该文件和 history 一样属于临时容器文件层，Space 重启后会丢失。
|
| 56 |
-
|
| 57 |
-
这个日志只能证明请求到达了当前运行中的容器，不能让 Hugging Face 把 Space 视为永久活跃，也不能阻止平台按免费硬件的闲置策略休眠或回收。若 Space 已经休眠，UptimeRobot 的请求通常只能触发一次唤醒/返回启动中的状态，是否重新启动及响应时间由 Hugging Face 平台决定；请以 Space Runtime 状态和平台政策为准。
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|