john
187 lines
5.5 KiB
Markdown
187 lines
5.5 KiB
Markdown
# 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://<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`（旧发布页兼容/存量发布根，不是当前 MindSpace Service 根目录）
|
|
|
|
代码生成 `imgproxy` URL 时，传进去的是 `asset.storage_key`，例如：
|
|
|
|
```text
|
|
users/<userId>/temp/<file>.upload
|
|
```
|
|
|
|
`imgproxy-signer.mjs` 会把它转成：
|
|
|
|
```text
|
|
local://users/<userId>/temp/<file>.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` 为准。
|