john
54de1dd8e3
DNS/TLS/proxy scripts and docs/local-dev.md replace localhost URLs for H5, memind_adm, Plaza, and Ops during local dev. Co-authored-by: Cursor <cursoragent@cursor.com>
127 lines
3.5 KiB
Markdown
127 lines
3.5 KiB
Markdown
# 本地开发（test.*.tkmind.cn）
|
||
|
||
本地开发统一使用 **test 子域**，不再用 `127.0.0.1` / `localhost` 访问。结构与生产一致，`.tkmind.cn` Cookie 可跨子域共享登录态。
|
||
|
||
## 域名映射
|
||
|
||
| 域名 | 服务 | 内部端口 |
|
||
|------|------|----------|
|
||
| **test.tkmind.cn** | MindSpace H5（Vite 热更新） | 5173 |
|
||
| **testadm.tkmind.cn** | memind_adm 后台 API | 8082 |
|
||
| **testpla.tkmind.cn** | Plaza 发现广场 | 3001 |
|
||
| **testops.tkmind.cn** | Ops 审核 / 超管 SPA | 3002 |
|
||
|
||
Portal（用户 API、登录、`/auth`）仍跑在 **8081**，由 Vite / Plaza 内部代理，**无需单独域名**。
|
||
|
||
```
|
||
浏览器
|
||
↓ HTTPS :443（local-test-proxy，按 Host 分流）
|
||
├─ test.tkmind.cn → :5173 Vite（/api、/auth → :8081）
|
||
├─ testadm.tkmind.cn → :8082 memind_adm
|
||
├─ testpla.tkmind.cn → :3001 Plaza Next.js
|
||
└─ testops.tkmind.cn → :3002 Ops SPA
|
||
```
|
||
|
||
## 首次配置（一次性）
|
||
|
||
```bash
|
||
# 1. 安装依赖
|
||
pnpm install
|
||
cd ops && npm install && cd ..
|
||
|
||
# 2. 环境变量（按需）
|
||
cp .env.example .env
|
||
|
||
# 3. 本地 DNS（覆盖 Tailscale / Clash fake-ip）
|
||
sudo pnpm setup:local-test
|
||
|
||
# 或分步：
|
||
# sudo pnpm setup:local-dns
|
||
# sudo pnpm setup:local-tls
|
||
```
|
||
|
||
`.env` 建议至少设置：
|
||
|
||
```bash
|
||
H5_PUBLIC_BASE_URL=https://test.tkmind.cn
|
||
H5_COOKIE_DOMAIN=.tkmind.cn
|
||
PLAZA_LOCAL_HOST=testpla.tkmind.cn
|
||
PLAZA_PUBLIC_BASE=https://testpla.tkmind.cn
|
||
ADMIN_PUBLIC_HOST=testadm.tkmind.cn
|
||
PLAZA_APP_DIR=/Users/john/PycharmProjects/goose/ui/plaza # Plaza 源码路径
|
||
```
|
||
|
||
## 日常启动
|
||
|
||
**终端 1 — 全栈开发：**
|
||
|
||
```bash
|
||
PLAZA_APP_DIR=/Users/john/PycharmProjects/goose/ui/plaza pnpm dev
|
||
```
|
||
|
||
**终端 2 — HTTPS 统一入口（需 root）：**
|
||
|
||
```bash
|
||
sudo pnpm dev:local-proxy
|
||
```
|
||
|
||
## 访问地址
|
||
|
||
| 场景 | 地址 |
|
||
|------|------|
|
||
| MindSpace | https://test.tkmind.cn/?preview=mindspace |
|
||
| Plaza | https://testpla.tkmind.cn/plaza |
|
||
| Ops 审核后台 | https://testops.tkmind.cn/ops/ |
|
||
| memind_adm 健康检查 | https://testadm.tkmind.cn/healthz |
|
||
| 一键打开 H5 | `pnpm open:local-test` |
|
||
|
||
## 诊断
|
||
|
||
```bash
|
||
pnpm check:local-test
|
||
```
|
||
|
||
## Ops 首次授权
|
||
|
||
先在 MindSpace 登录，再执行：
|
||
|
||
```bash
|
||
node scripts/grant-ops-role.mjs admin ops_admin
|
||
```
|
||
|
||
## 浏览器「连接不是私密连接」？
|
||
|
||
本地 HTTPS 使用自签证书（`.local/local-test-tls/`）。首次访问各 test 域名时，在浏览器中信任证书即可。
|
||
|
||
若 Chrome 仍走 Secure DNS 绕过 `/etc/hosts`：
|
||
|
||
1. 关闭「使用安全 DNS」
|
||
2. 或执行 `pnpm open:local-test`
|
||
|
||
## 移除本地劫持
|
||
|
||
```bash
|
||
sudo pnpm setup:local-dns:remove
|
||
```
|
||
|
||
## 与 plaza.tkmind.cn 的关系
|
||
|
||
- **testpla.tkmind.cn**：纯本地开发，不与公网冲突
|
||
- **plaza.tkmind.cn**：公网 Tunnel 回源，见 [plaza-local.md](./plaza-local.md)
|
||
|
||
两套域名可并存；日常 Memind 全栈开发优先用 `test.*`。
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 默认 | 说明 |
|
||
|------|------|------|
|
||
| `H5_LOCAL_HOST` | test.tkmind.cn | H5 测试域 |
|
||
| `ADMIN_LOCAL_HOST` | testadm.tkmind.cn | 后台 API 测试域 |
|
||
| `PLAZA_LOCAL_HOST` | testpla.tkmind.cn | Plaza 测试域 |
|
||
| `OPS_LOCAL_HOST` | testops.tkmind.cn | Ops 测试域 |
|
||
| `H5_PUBLIC_BASE_URL` | https://test.tkmind.cn | 公开链接 / OAuth 回调基址 |
|
||
| `H5_COOKIE_DOMAIN` | （建议 `.tkmind.cn`） | 跨子域共享登录 |
|
||
| `LOCAL_TEST_DNS_PORT` | 5533 | 本地 DNS 监听端口 |
|
||
| `LOCAL_TEST_PUBLIC_PORT` | 443 | HTTPS 代理端口 |
|
||
| `LOCAL_TEST_HTTPS` | 1 | 设为 `0` 时用 HTTP :80 |
|