Document plaza 105-to-studio flow

docs/plaza-local.md

@@ -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）
-    ↓  Cloudflare Tunnel
-本机 Mac
+105 公网入口（plaza.tkmind.cn）
+    ↓  nginx / 反代
+Studio / 本机生产机
     ├─ :3001  Plaza Next.js（/plaza、/_next）
     │         └─ rewrites → :8081（/api、/auth、/u）
     └─ :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
-# 1. 本地 DNS（覆盖 Tailscale / Clash fake-ip）
-sudo pnpm setup:plaza-dns
-
-# 2. 本地 HTTPS 证书（可选，供本机 https://plaza.tkmind.cn）
-sudo pnpm setup:plaza-local
-
-# 3. 公网隧道（plaza.tkmind.cn → 本机 :3001）
-pnpm setup:plaza-tunnel
-```
+- 105 上 nginx 配置正常，`/plaza` 和 `/_next` 代理到 Studio
+- Studio 上 Plaza 已完成 `next build`
+- Studio 上 Plaza 生产进程正在监听 `127.0.0.1:3001`
+- Studio 上 Portal 正在监听 `127.0.0.1:8081`
 
 ## 日常启动
 
 ```bash
-# 本机正式模式（next build + start，供 Tunnel 回源，推荐公网）
+# Studio 上启动 Plaza 生产模式
 pnpm start:plaza
 
 # 开发模式（热更新，仅本地调试）
 pnpm dev:plaza
 
-# 另开终端：本机 HTTPS 入口（可选，纯本地 HTTPS 时用）
-sudo pnpm dev:plaza-proxy
-
-# 或全栈（MindSpace + Plaza + Ops）
+# 全栈（MindSpace + Plaza + Ops）
 pnpm dev
 ```
 
@@ -51,61 +42,30 @@ pnpm dev
 | 场景 | 地址 |
 |------|------|
 | 本机直连 | http://127.0.0.1:3001/plaza |
-| 本机域名（需 proxy） | https://plaza.tkmind.cn/plaza |
+| 105 公网入口 | https://plaza.tkmind.cn/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`（推荐）
-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 前缀 |
+- `next/font/google` 在离线构建时会拉不到字体资源
+- 类型检查会因为事件批处理数组的推断过宽而失败
 
 ## 已弃用
 
-- `pnpm deploy:105`、`pnpm deploy:plaza-105` — 105 不再作为主服务
-- 105 上 nginx / goose-h5 / goose-plaza-web — 已停服，公网不再回源 105
+- 把 `plaza.tkmind.cn` 直接指到本机 `127.0.0.1` 的旧本地劫持流程
+- 直接把 `plaza.tkmind.cn` 说明成 Cloudflare Tunnel 直连本机的旧说法
+- “105 已停用、Plaza 全在本机且不经过 105”的旧文档描述