docs: record test environment handoff

2026-08-02 00:13:43 +08:00
parent 73905453a5
commit ca4cbf072f
1 changed files with 8 additions and 0 deletions
@@ -150,6 +150,10 @@ Set-Location D:\www\gs-sport-era; powershell -ExecutionPolicy Bypass -File .\scr
 - Docker crawler 任务真实执行入口是 `sport-era-crawler` 容器。更新 `docker/crawler` 源码或 `config/crawler_tasks.yaml` 后，必须在服务器 `docker` 目录执行 `sudo docker compose -f docker-compose.crawler.yml build crawler` 和 `sudo docker compose -f docker-compose.crawler.yml up -d --no-deps crawler`；仅重启旧容器不能保证镜像内代码更新，必要时使用 `--no-cache` 重建。
 - 重启 crawler 后必须核验容器内代码和 cron，而不是只看宿主机源码：例如检查 `/app/match_live_stream.py`、`/app/config/crawler_tasks.yaml`，以及 `cat /etc/cron.d/* | grep match_live_stream`。
 - 雨燕直播间任务 `match_live_stream` 当前应直接同步 `all_live_rooms.json`，写入主播 `anchor_id`、`anchor_name`、`anchor_avatar`、`anchor_level` 以及直播间观看/关注/公告/简介字段；对应 SQL 为 `docs/sql/alter_match_live_anchor_fields.sql` 和 `docs/sql/insert_crontab_match_live_stream.sql`。上线后用 `la_match_live` 主播字段统计和 `la_crawler_task_log` 最近任务状态共同确认是否生效。
+- 测试服当前使用 Git 分支 `dev.1.0.0`，真实目录为 `/www/wwwroot/test-server.sbnews.net`。同步前先确认远端 `origin`、分支和工作区状态；不要在服务器上用 root 执行日常 `git pull`，否则可能让 `.git/objects` 出现 root/www/ubuntu 混合权限。
+- 测试环境域名反代关系：`test-admin.sbnews.net` → 宿主机 `5176`（Admin Vite）、`testh5.sbnews.net` → `5177`（uni-app H5 Vite）、`test-server.sbnews.net` → `8000`（Docker Nginx/PHP API）。宿主机 Nginx 配置位于 `/www/server/panel/vhost/nginx/` 和对应 `rewrite/` 目录，修改后必须执行 `sudo nginx -t && sudo systemctl reload nginx`。
+- `docker/docker-compose.dev.yml` 当前包含 `crawler` 服务；PHP、scheduler、crawler、Docker Nginx 使用 host network 访问测试服 MySQL/Redis。测试服私有 `docker/.env.server`、`docker/.env.docker` 不入库，数据库/Redis 密码不得写入 Git。
+- `sport-era-kb-worker` 使用 `docker/docker-compose.crawler.yml`，通过 Redis Stream `ai:kb:sync:stream` 消费知识库任务并生成 Embedding，写入 `la_ai_kb_document`/`la_ai_kb_chunk`。测试账号仅授权 `127.0.0.1` 时，worker 必须使用 host network；crawler 镜像需要 `cryptography` 才能连接 MySQL `caching_sha2_password` 认证。

 ## 近期踩坑

@@ -159,3 +163,7 @@ Set-Location D:\www\gs-sport-era; powershell -ExecutionPolicy Bypass -File .\scr
 - 构建产生的 `server/public/admin`、`server/public/mobile` 等产物不要混进提交，提交前先清理临时截图和生成文件。
 - **uni-app iOS 端 scroll-view+JS 计算高度 间隙问题**：在 iOS（APP-PLUS/MP）端，通过 `uni.createSelectorQuery()` 计算 `windowHeight - topBar - inputBar` 然后设置 `scroll-view` 的 inline `height` 会因安全区域、设备像素比等因素产生几像素偏差，导致 `scroll-view` 底部与固定输入栏之间出现间隙。**正确做法**：页面使用 `height: 100vh; display: flex; flex-direction: column`，topbar 和 input-bar 设 `flex-shrink: 0`，scroll-view 设 `flex: 1; min-height: 0` 自然填满剩余空间，不再用 JS 计算高度。
 - **Vue3 `<script setup>` 中 `defineEmits` 和 `defineProps` 返回值必须赋值**：`defineEmits(...)` 的返回值才是可调用的 emit 函数，直接写 `defineEmits([...])` 不赋值会导致 "Can't find variable: emit"；`defineProps` 的返回值才能通过 `props.xxx` 访问属性，模板中自动解包但脚本中必须用 `props.xxx`。
+- **服务器 Git 权限**：如果 `git pull` 报 `insufficient permission for adding an object to repository database .git/objects`，通常是之前用 `sudo git` 造成 `.git` 混合所有者。只修复 Git 元数据：`sudo chown -R ubuntu:ubuntu .git && sudo chmod -R u+rwX .git`，不要对整个项目目录递归改所有者。
+- **服务器 Git 拉取被未跟踪文件阻塞**：如果提示 `.playwright-mcp/* would be overwritten by merge`，这些是浏览器检查生成物。先把明确目录移到 `/tmp` 备份或删除，再执行 `git pull --ff-only`；不要使用无范围的 `git clean -fd`。
+- **测试域名首屏慢的根因**：Admin/H5 当前是 Vite 开发服务器，首轮按需转换大量模块，浏览器首屏可能需要 20–40 秒；宿主机 Nginx 反代本身约几百毫秒。需要快速访问时应构建生产静态资源并由 Nginx 直接托管，但这会改变频繁改代码的即时生效方式。
+- **uni-app H5 API 地址**：H5 浏览器不能请求 `http://127.0.0.1:8000`，这会被浏览器当作用户本机回环地址并触发 CORS/Private Network 拦截。测试域名应使用 `https://test-server.sbnews.net/` 或同域反代路径；修改后需重启/刷新 H5 Vite 服务。