infinite-canvas-local-proxy 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# infinite-canvas-local-proxy
+
+Infinite Canvas 的本地转发代理。浏览器直连第三方 AI 接口时经常被 CORS 拦截，启动它之后，网页会把请求先发到本机，再由本机转发到目标地址。代理还提供本地持久化任务，用于页面关闭或刷新后恢复图片/视频生成请求。
+
+普通代理请求仍是透明转发，不改写请求体，也不保存请求与响应。
+
+## 使用
+
+```bash
+npx infinite-canvas-local-proxy@latest
+```
+
+默认监听 `http://127.0.0.1:23210`。把这个地址填进 Infinite Canvas 的「配置 → 本地代理」，并打开开关即可。
+
+带上 `@latest` 是因为 npx 会缓存已下载的版本，不加就可能一直运行旧版本。
+
+可选参数：
+
+```bash
+npx infinite-canvas-local-proxy@latest --port 23210 --host 127.0.0.1
+```
+
+也支持 `PORT` / `HOST` 环境变量。
+
+## 转发规则
+
+把完整目标地址接在代理地址后面：
+
+```
+http://127.0.0.1:23210/https://api.openai.com/v1/models
+        └─── 代理地址 ──┘└──────── 目标地址 ────────┘
+```
+
+请求方法、请求头（除 `host` 等逐跳头外）、请求体原样转发；响应状态码、响应头和响应体原样返回，并补上宽松的 CORS 头。SSE 流式响应按块透传，不做缓冲。
+
+访问根路径 `/` 会返回代理版本信息，可用于连通性检测，不会记入转发日志。
+
+## 转发日志
+
+普通转发请求会在终端打印一行，包含时间、方法、目标地址、上游状态码和耗时：
+
+```
+4:05:42 PM GET https://api.openai.com/v1/models -> 200 0.9s
+4:05:43 PM POST https://api.openai.com/v1/images/generations -> 200 26.4s
+4:05:45 PM GET https://api.example.com/v1/models -> failed (fetch failed) 1.6s
+```
+
+日志在收到上游响应头时打印，所以流式请求会立刻出现一行，而不是等整段响应结束。此日志不包含请求头和请求体。持久化任务只输出随机任务 ID 前缀、完成状态和耗时，不记录目标地址或凭证。
+
+## 持久化图片与视频任务
+
+前端在发送生成请求前会保存稳定的 `clientRequestId`，再由代理把请求记录写入 SQLite 并返回接受状态。相同 ID 的重试会关联到已有任务，不会再次提交上游请求；即使创建响应丢失，也能按该 ID 查询状态和结果。同步图片请求及原生 OpenAI/Gemini 视频的创建、供应商状态轮询和结果保存均由代理后台执行，浏览器只轮询本地任务状态。
+
+自定义图片/视频脚本可由代理执行其 `create`/`poll` 协议，页面关闭时代理仍可继续轮询脚本任务。`http`、`request`、`fetch`、`poll`、`sleep` 和 `cacheMediaUpload` 等脚本能力也可用；媒体上传 URL 缓存只在当前代理进程内有效。后台脚本支持 `FileReader.readAsDataURL`，但并非完整浏览器环境；`fetch` 不支持流式请求体。自定义脚本按可信的本机代码处理：Node.js `vm` 不是安全隔离边界，不要运行不信任的脚本，也不要将代理端口暴露给其他设备。
+
+- 默认数据目录为用户主目录下的 `.canvas-proxy`（Windows 为 `%USERPROFILE%\.canvas-proxy`），包括 `tasks.sqlite`、SQLite 日志文件和 `results/` 响应文件。备份时需停止代理后复制整个目录。
+- API Key、请求头和请求体仅在代理内存中用于上游请求；任务请求体、脚本上下文及 API Key 不写入数据库或任务日志。若上游响应或脚本错误中发现已识别的凭证原文，该结果不会保存或会在错误中脱敏。
+- 图片/视频脚本请求支持 JSON、文本、URL 编码和 multipart/form-data；multipart 文件在本地任务创建请求中临时 Base64 编码，代理端重建为 multipart 后发送。请求体总大小上限 80 MiB；独立二进制请求体不支持。
+- 默认最多同时执行 2 个任务、最多保留 4 个排队/运行任务；请求体上限 80 MiB、上游响应上限 100 MiB、单任务等待上限 30 分钟，成功/失败记录保留 24 小时。
+- 可通过环境变量 `CANVAS_PROXY_DATA_DIR`、`CANVAS_PROXY_TASK_CONCURRENCY`、`CANVAS_PROXY_TASK_OUTSTANDING_LIMIT`、`CANVAS_PROXY_TASK_REQUEST_LIMIT_BYTES`、`CANVAS_PROXY_TASK_RESPONSE_LIMIT_BYTES`、`CANVAS_PROXY_TASK_TIMEOUT_MS` 和 `CANVAS_PROXY_TASK_RETENTION_MS` 调整目录与限制。
+- 代理进程重启时，原来排队或运行中的任务标记为“结果未知”，不会自动再次提交上游请求，以避免重复计费。已完成结果仍可从数据库记录和响应文件恢复，直至过期。
+- 代理只报告 queued/running/polling/完成/失败等本地状态，不提供或伪造供应商生成百分比。代理必须保持运行，才能在浏览器关闭后继续执行代理持有的请求或自定义脚本轮询。
+
+现有 `/api/tasks` 及查询路由不要求额外认证，任务 ID 是高熵随机能力令牌。因此，默认只监听 `127.0.0.1`；不要把代理端口暴露到公网或不可信局域网。远程部署需另行配置认证与访问控制。
+
+## 安全提示
+
+代理默认只监听 `127.0.0.1`，仅本机可访问。它会转发任何请求到任何地址，请不要用 `--host 0.0.0.0` 暴露到公网。普通代理请求中的 API Key 由浏览器持有并随请求转发；持久化任务的 API Key 仅在代理内存中短暂使用，不持久化。
+
+## 环境要求
+
+Node.js >= 18。不需要 Python、Visual Studio 编译工具，也不需要任何原生模块通过编译——安装阶段不会触发 `node-gyp`。
+
+### 任务存储的三种后端
+
+代理会按顺序自动挑选，不需要手动配置：
+
+| 后端 | 条件 | 任务是否持久化 |
+|---|---|---|
+| `better-sqlite3` | 安装成功且与当前 Node 的 ABI 匹配 | 是 |
+| `node:sqlite` | Node 22.5 及以上（内置） | 是 |
+| `memory` | 上面两者都不可用 | 否，重启后清空 |
+
+启动日志和根路径 `GET /` 会显示当前使用的后端，例如：
+
+```json
+{"taskStore":"node:sqlite","persistentTasks":true,"node":"22.22.2"}
+```
+
+`better-sqlite3` 是可选依赖。某些 Node 版本（如 24）没有对应的预编译产物，安装时会尝试本地编译并失败，但 **npm 会跳过它并继续**，代理随后自动改用内置的 `node:sqlite`，功能不受影响。
+
+Node 22.5 及以上首次加载内置 SQLite 时会打印一行 `ExperimentalWarning: SQLite is an experimental feature`，这是 Node 自身的提示，不影响使用。
+
+### 安装报错的排查
+
+如果看到 `prebuild-install warn install No prebuilt binaries found` 并跟着一长串 `gyp ERR! find Python`，说明当前 Node 版本没有 `better-sqlite3` 的预编译产物，于是退回到本地编译，而机器上又没装 Python。这种情况在新版本 Node 上很常见。
+
+0.2.1 起这个错误不会再中断安装。如果仍想彻底消除，任选其一：
+
+- 升级到 Node 22 LTS 或更高，走内置 `node:sqlite`，完全不需要编译
+- 或者安装 Python 3 与 Visual Studio Build Tools，让 `better-sqlite3` 能编译
+
+清除安装残留：
+
+```bash
+rmdir /s /q "%LocalAppData%\npm-cache\_npx"     # Windows
+npm cache clean --force
+```
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.