memind/docs/plaza-local.md

# Plaza 本机为主

105 服务器已停用。Plaza 与 Memind H5 均在本机 Mac 运行；公网 `plaza.tkmind.cn` 经 **Cloudflare Tunnel** 回源到本机。

## 架构

```
浏览器 / 微信
    ↓
Cloudflare（plaza.tkmind.cn）
    ↓  Cloudflare Tunnel
本机 Mac
    ├─ :3001  Plaza Next.js（/plaza、/_next）
    │         └─ rewrites → :8081（/api、/auth、/u）
    └─ :8081  Memind Portal（server.mjs）
```

Next.js 通过 `PLAZA_API_PROXY` 把 API 请求转发到 Portal，无需单独 nginx。

## 首次配置（一次性）

```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
```

## 日常启动

```bash
# 本机正式模式（next build + start，供 Tunnel 回源，推荐公网）
pnpm start:plaza

# 开发模式（热更新，仅本地调试）
pnpm dev:plaza

# 另开终端：本机 HTTPS 入口（可选，纯本地 HTTPS 时用）
sudo pnpm dev:plaza-proxy

# 或全栈（MindSpace + Plaza + Ops）
pnpm dev
```

## 访问方式

| 场景 | 地址 |
|------|------|
| 本机直连 | http://127.0.0.1:3001/plaza |
| 本机域名（需 proxy） | 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，应 **去掉本地劫持**，走公网证书（仍回源本机）：

```bash
sudo pnpm setup:plaza-dns:remove
```

然后刷新 https://plaza.tkmind.cn/ 即可。

### 浏览器打不开？

Chrome / Cursor 内置浏览器默认走 **Secure DNS**，会绕过 `/etc/hosts` 连到 Cloudflare（105 停服时显示 502）。

解决：

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 前缀 |
| `VITE_PLAZA_BASE` | （见下） | Portal 前端「逛 Plaza」链接；**编译期**写入 dist |

### Portal「逛 Plaza」链接（MindSpace / 发布成功页）

Plaza 是独立域名 `plaza.tkmind.cn`，与 Portal `m.tkmind.cn` 不同。前端通过 `src/utils/publicUrl.ts` → `public-site-bases.mjs` 解析：

| 环境 | 期望链接 |
|------|----------|
| 本机 `127.0.0.1` / `localhost` | `http://127.0.0.1:3001/plaza` |
| 生产 `m.tkmind.cn` | `https://plaza.tkmind.cn/plaza` |

**为何生产曾出现 127？** `VITE_*` 在 `vite build` 时写入 bundle。若本机 `.env` 含 `VITE_PLAZA_BASE=http://127.0.0.1:3001`，未覆盖就直接打生产包，会把 127 带进 `m.tkmind.cn`。

**彻底修复（三层）：**

1. **运行时守卫**：在 `m.tkmind.cn` 等公网 host 上，即使 bundle 内是 loopback，也强制用 `https://plaza.tkmind.cn`（见 `public-site-bases.mjs`）。
2. **构建默认值**：`scripts/build-portal-runtime.mjs` 在未显式设置时注入 `VITE_PLAZA_BASE=https://plaza.tkmind.cn`。
3. **勿在生产构建用本地 .env**：发 Portal runtime 前确认 `npm run build` / `build-portal-runtime.mjs` 未读取带 127 的 `VITE_PLAZA_BASE`。

验证：

```bash
node --test public-site-bases.test.mjs
```

## 已弃用

- `pnpm deploy:105`、`pnpm deploy:plaza-105` — 105 不再作为主服务
- 105 上 nginx / goose-h5 / goose-plaza-web — 已停服，公网不再回源 105