memind/docs/imgproxy-103-production-runbook.md

ImgProxy 103 生产部署说明

目标：把 imgproxy 部署到 103 / Studio，保持和当前本机开发一致的签名配置、端口约定、数据根语义与 URL 生成方式。

先说结论

可以做到“行为一模一样”，但不应该追求把本机 /Users/john/... 绝对路径逐字照搬到另一台机器。

当前代码真正依赖的是这几件事：

1. IMGPROXY_BASE_URL
2. IMGPROXY_SIGNING_KEY
3. IMGPROXY_SIGNING_SALT
4. MINDSPACE_STORAGE_ROOT
5. imgproxy 能从 local://<storage_key> 读到真实文件

也就是说，生产上要保持的是：

• 同一套签名 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

代码生成 imgproxy URL 时，传进去的是 asset.storage_key，例如：

users/<userId>/temp/<file>.upload

imgproxy-signer.mjs 会把它转成：

local://users/<userId>/temp/<file>.upload

所以生产 imgproxy 只需要把本地文件系统根指到：

/Users/john/Project/Memind/data/mindspace

这样 local://users/... 就能正确落到：

/Users/john/Project/Memind/data/mindspace/users/...

推荐的 103 配置

1. Portal .env

103 Portal 运行环境里建议保持：

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 本机监听：

127.0.0.1:20081

并使用：

IMGPROXY_LOCAL_FILESYSTEM_ROOT=/Users/john/Project/Memind/data/mindspace
IMGPROXY_KEY=<同 IMGPROXY_SIGNING_KEY>
IMGPROXY_SALT=<同 IMGPROXY_SIGNING_SALT>

仓库已补安装脚本：

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 其实已经满足：

/Users/john/Project/Memind/data/mindspace

这正是当前 103 的正式持久目录。

如果你的要求是“和你本地 Mac 开发时完全一样的 IMGPROXY_BASE_URL=http://localhost:20081”，那生产不该这么做，因为：

1. 页面生成后要给外部用户访问
2. 聊天里插图也要给前端访问
3. localhost 只对 103 自己有效，不对用户浏览器有效

所以这里唯一应该改的是 BASE_URL，不是签名和存储路径。

img.tkmind.cn 入口怎么接

推荐链路：

用户 -> 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 本机

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 日志里应继续看到：

[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 为准。