# ImgProxy 103 生产部署说明 > 目标：把 `imgproxy` 部署到 `103 / Studio`，保持和当前本机开发一致的签名配置、端口约定、数据根语义与 URL 生成方式。 > > 2026-07-03 更新：103 当前 MindSpace Service 根目录是 `/Users/john/MindSpace`。本文下面的 `/Users/john/Project/Memind/MindSpace` 只表示旧发布页兼容/存量目录；不要把它理解为当前 MindSpace Service 根目录。当前生产拓扑见 [103 runtime topology](./103-runtime-topology.md)。 ## 先说结论 可以做到“行为一模一样”，但**不应该追求把本机 `/Users/john/...` 绝对路径逐字照搬到另一台机器**。 当前代码真正依赖的是这几件事： 1. `IMGPROXY_BASE_URL` 2. `IMGPROXY_SIGNING_KEY` 3. `IMGPROXY_SIGNING_SALT` 4. `MINDSPACE_STORAGE_ROOT` 5. `imgproxy` 能从 `local://` 读到真实文件 也就是说，生产上要保持的是： - 同一套签名 key / salt - 同一个存储根语义 - 同一个监听端口 `127.0.0.1:20081` - 同一个公网域名入口 `https://img.tkmind.cn` 而不是把开发机 `localhost` 或别的绝对路径硬搬过去。 ## 当前仓库里的真实前提 103 当前真实持久目录已经固定为： - `H5_USERS_ROOT=/Users/john/Project/Memind/users` - `MINDSPACE_STORAGE_ROOT=/Users/john/Project/Memind/data/mindspace` - `MEMIND_SHARED_PUBLISH_ROOT=/Users/john/Project/Memind/MindSpace`（旧发布页兼容/存量发布根，不是当前 MindSpace Service 根目录） 代码生成 `imgproxy` URL 时，传进去的是 `asset.storage_key`，例如： ```text users//temp/.upload ``` `imgproxy-signer.mjs` 会把它转成： ```text local://users//temp/.upload ``` 所以生产 `imgproxy` 只需要把本地文件系统根指到： ```text /Users/john/Project/Memind/data/mindspace ``` 这样 `local://users/...` 就能正确落到： ```text /Users/john/Project/Memind/data/mindspace/users/... ``` ## 推荐的 103 配置 ### 1. Portal `.env` 103 Portal 运行环境里建议保持： ```env MINDSPACE_STORAGE_ROOT=/Users/john/Project/Memind/data/mindspace IMGPROXY_BASE_URL=https://img.tkmind.cn IMGPROXY_SIGNING_KEY=<与当前开发一致> IMGPROXY_SIGNING_SALT=<与当前开发一致> ``` 说明： - `IMGPROXY_BASE_URL` 在生产不能再用 `http://localhost:20081`，因为最终生成给页面和聊天的 URL 应该是公网可访问域名。 - `IMGPROXY_SIGNING_KEY` / `IMGPROXY_SIGNING_SALT` 必须和当前代码生成器一致，否则已发布页面与聊天里的图片链接会全部失效。 ### 2. ImgProxy 进程 建议在 `103 / Studio` 本机监听： ```text 127.0.0.1:20081 ``` 并使用： ```text IMGPROXY_LOCAL_FILESYSTEM_ROOT=/Users/john/Project/Memind/data/mindspace IMGPROXY_KEY=<同 IMGPROXY_SIGNING_KEY> IMGPROXY_SALT=<同 IMGPROXY_SIGNING_SALT> ``` 仓库已补安装脚本： ```bash bash scripts/install-imgproxy-prod.sh ``` 它会： 1. 检查 Homebrew `imgproxy` 2. 读取当前 `.env` 3. 生成 `~/Library/LaunchAgents/cn.tkmind.imgproxy.plist` 4. 以 LaunchAgent 方式启动 `imgproxy` 5. 监听 `127.0.0.1:20081` ## 为什么这已经算“同路径” 如果你的要求是“和本机当前项目路径一致”，那 103 其实已经满足： ```text /Users/john/Project/Memind/data/mindspace ``` 这正是当前 103 的正式持久目录。 如果你的要求是“和你本地 Mac 开发时完全一样的 `IMGPROXY_BASE_URL=http://localhost:20081`”，那生产不该这么做，因为： 1. 页面生成后要给外部用户访问 2. 聊天里插图也要给前端访问 3. `localhost` 只对 103 自己有效，不对用户浏览器有效 所以这里唯一应该改的是 `BASE_URL`，不是签名和存储路径。 ## `img.tkmind.cn` 入口怎么接 推荐链路： ```text 用户 -> img.tkmind.cn -> 103 Caddy -> 127.0.0.1:20081 imgproxy ``` 注意一个当前限制： - 仓库里虽然有 `/api/mindspace/v1/authorize-image` - 但现有 `imgproxy-signer.mjs` 生成的 URL **没有附带 `asset_id` query** - 因此 `forward_auth` 目前没有足够信息做“按资产鉴权” 所以在当前代码下，`img.tkmind.cn` 这层**先不要假装已经接好了 `forward_auth`**。 现阶段更准确的说法是： - 已具备 `imgproxy` 签名和反代条件 - 但若要做“按资产授权”的反代鉴权，还需要先扩展 URL 方案，把 `asset_id` 或等价标识带进请求 ## 建议发布顺序 1. 本地 commit 当前分支 2. 发布 Portal runtime 到 103 3. 在 103 更新 `.env` 的 `IMGPROXY_BASE_URL=https://img.tkmind.cn` 4. 在 103 执行 `bash scripts/install-imgproxy-prod.sh` 5. 验证 `curl -i http://127.0.0.1:20081/health` 6. 再接 `img.tkmind.cn` 的 Caddy 入口 7. 用一条真实 MindSpace 图片 URL 验证页面和聊天渲染 ## 最小验收 ### 103 本机 ```bash curl -i http://127.0.0.1:20081/health launchctl list | grep cn.tkmind.imgproxy tail -n 50 ~/Library/Logs/imgproxy.log ``` ### Portal URL 生成 启动后的 Portal 日志里应继续看到： ```text [Publication] imgproxy signer initialized [TKMindProxy] imgproxy signer initialized ``` ### 业务验收 至少验证三条： 1. MindSpace 公开页图片能显示 2. 聊天消息里引用的图片能显示 3. 旧的 `/api/mindspace/v1/assets/.../download` 公开图链不再作为首选发布路径 ## 风险提示 当前 `g2-lb.Caddyfile` 里关于 `img.tkmind.cn` 的注释历史上把入口位置写成了 `105`，这已经不符合现在的真实架构。 真实运行位应当以 `103 / Studio` 为准。