tkmind/memind
1
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

Document plaza 105-to-studio flow

Browse Source
This commit is contained in:
john
2026-06-20 15:39:19 +08:00
parent 2f07f3733e
commit 44e962e270
1 changed files with 29 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/plaza-local.md
+29 -69
View File
@@ -1,48 +1,39 @@
# Plaza 本机为主 # Plaza 由 105 入口转发到 Studio
105 服务器已停用。Plaza 与 Memind H5 均在本机 Mac 运行；公网 `plaza.tkmind.cn` 经 **Cloudflare Tunnel** 回源到本机。 `plaza.tkmind.cn` 现在解析到 105 服务器，105 只负责公网入口和反代，最终回源到 Studio 上的 Plaza 生产服务。
## 架构 ## 架构
``` ```text
浏览器 / 微信 浏览器 / 微信
↓ ↓
Cloudflare（plaza.tkmind.cn） 105 公网入口（plaza.tkmind.cn）
↓ Cloudflare Tunnel ↓ nginx / 反代
本机 Mac Studio / 本机生产机
├─ :3001 Plaza Next.js（/plaza、/_next） ├─ :3001 Plaza Next.js（/plaza、/_next）
│ └─ rewrites → :8081（/api、/auth、/u） │ └─ rewrites → :8081（/api、/auth、/u）
└─ :8081 Memind Portal（server.mjs） └─ :8081 Memind Portal（server.mjs）
``` ```
Next.js 通过 `PLAZA_API_PROXY` 把 API 请求转发到 Portal，无需单独 nginx。 Next.js 通过 `PLAZA_API_PROXY` 把 API 请求转发到 Portal，无需单独 nginx。105 侧只负责把 `https://plaza.tkmind.cn/plaza` 回源到 Studio 的 `:3001`。
## 首次配置（一次性） ## 运行前提
```bash - 105 上 nginx 配置正常，`/plaza` 和 `/_next` 代理到 Studio
# 1. 本地 DNS（覆盖 Tailscale / Clash fake-ip） - Studio 上 Plaza 已完成 `next build`
sudo pnpm setup:plaza-dns - Studio 上 Plaza 生产进程正在监听 `127.0.0.1:3001`
- Studio 上 Portal 正在监听 `127.0.0.1:8081`
# 2. 本地 HTTPS 证书（可选，供本机 https://plaza.tkmind.cn）
sudo pnpm setup:plaza-local
# 3. 公网隧道（plaza.tkmind.cn → 本机 :3001）
pnpm setup:plaza-tunnel
```
## 日常启动 ## 日常启动
```bash ```bash
# 本机正式模式（next build + start，供 Tunnel 回源，推荐公网） # Studio 上启动 Plaza 生产模式
pnpm start:plaza pnpm start:plaza
# 开发模式（热更新，仅本地调试） # 开发模式（热更新，仅本地调试）
pnpm dev:plaza pnpm dev:plaza
# 另开终端：本机 HTTPS 入口（可选，纯本地 HTTPS 时用） # 全栈（MindSpace + Plaza + Ops）
sudo pnpm dev:plaza-proxy
# 或全栈（MindSpace + Plaza + Ops）
pnpm dev pnpm dev
``` ```
@@ -51,61 +42,30 @@ pnpm dev
| 场景 | 地址 | | 场景 | 地址 |
|------|------| |------|------|
| 本机直连 | http://127.0.0.1:3001/plaza | | 本机直连 | http://127.0.0.1:3001/plaza |
| 本机域名（需 proxy） | https://plaza.tkmind.cn/plaza | | 105 公网入口 | https://plaza.tkmind.cn/plaza |
| 浏览器强制本地 | `pnpm open:plaza` | | 浏览器强制本地 | `pnpm open:plaza` |
| 公网（需 dev:plaza + 隧道） | https://plaza.tkmind.cn/plaza |
### 浏览器提示「连接不是私密连接」？ ## 常见故障
本机曾用 `setup:plaza-dns` 把域名指到 `127.0.0.1`，HTTPS 走自签证书。若已配置 Cloudflare Tunnel，应 **去掉本地劫持**，走公网证书（仍回源本机）： ### 访问 502
```bash 优先按这个顺序检查：
sudo pnpm setup:plaza-dns:remove
```
然后刷新 https://plaza.tkmind.cn/ 即可。 1. Studio 上 `http://127.0.0.1:3001/plaza` 是否返回 200
2. Studio 上 Plaza 生产进程是否还在
3. 105 上 nginx 是否已经 reload 到最新配置
### 浏览器打不开？ 如果 Studio 的 `:3001` 没起来，105 再怎么转发也会 502。
Chrome / Cursor 内置浏览器默认走 **Secure DNS**，会绕过 `/etc/hosts` 连到 Cloudflare（105 停服时显示 502）。 ### Studio 启动失败
解决： 如果 `pnpm start:plaza` 一直退出，优先看 `~/Library/Logs/plaza-prod.log`。这次修复里我们遇到过两类问题：
1. `pnpm open:plaza`（推荐） - `next/font/google` 在离线构建时会拉不到字体资源
2. 关闭浏览器「安全 DNS / Secure DNS」 - 类型检查会因为事件批处理数组的推断过宽而失败
3. `pnpm check:plaza` 查看诊断
## 公网 Tunnel
隧道配置写在 `ollama-tkmind` 的 cloudflared config（默认 `~/Project/ollama/cloudflare/config.yml`）。
```bash
pnpm setup:plaza-tunnel # 写入 ingress + DNS 路由 + 重启 cloudflared
```
**前提：** `pnpm start:plaza`（或 `pnpm dev:plaza`）已在跑（:3001 可访问）。Mac 休眠或服务停掉时，外网会 502/503。
自定义：
```bash
CLOUDFLARE_TUNNEL_CONFIG=/path/to/config.yml \
CLOUDFLARE_TUNNEL_NAME=ollama-tkmind \
PLAZA_TUNNEL_PORT=3001 \
pnpm setup:plaza-tunnel
```
## 环境变量
见 `.env.example` 中 Plaza 相关注释。常用：
| 变量 | 默认 | 说明 |
|------|------|------|
| `PLAZA_PORT` | 3001 | Plaza Next.js 端口 |
| `H5_PORT` | 8081 | Portal / API 端口 |
| `PLAZA_LOCAL_HOST` | plaza.tkmind.cn | 本地域名 |
| `PLAZA_PUBLIC_BASE` | https://plaza.tkmind.cn | 公开 URL 前缀 |
## 已弃用 ## 已弃用
- `pnpm deploy:105`、`pnpm deploy:plaza-105` — 105 不再作为主服务 - 把 `plaza.tkmind.cn` 直接指到本机 `127.0.0.1` 的旧本地劫持流程
- 105 上 nginx / goose-h5 / goose-plaza-web — 已停服，公网不再回源 105 - 直接把 `plaza.tkmind.cn` 说明成 Cloudflare Tunnel 直连本机的旧说法
- “105 已停用、Plaza 全在本机且不经过 105”的旧文档描述