167 lines
8.9 KiB
Markdown
167 lines
8.9 KiB
Markdown
# CaiWuXiTong 本地测试环境
|
||
|
||
本说明用于开发者在自己的电脑上启动项目。项目使用 Docker，默认访问地址为：
|
||
|
||
```text
|
||
http://127.0.0.1:18088
|
||
```
|
||
|
||
新人只需要启动 Docker Desktop、在网页中登录，并输入一次系统数据库密码。拉取代码、执行初始化、迁移本机引导库、启动服务、清理缓存、验证系统数据库、同步数据字典和验证两套上游均由 Codex 完成。
|
||
|
||
## 先理解数据库关系
|
||
|
||
本地 Compose 中的 MySQL 只负责第一次启动，让开发者能够使用临时账号进入系统。
|
||
|
||
登录后必须在：
|
||
|
||
```text
|
||
系统设置 → 数据库管理 → 系统数据库 → 连接
|
||
```
|
||
|
||
只填写负责人提供的系统数据库密码并点击“连接系统数据库”。连接成功后：
|
||
|
||
- 用户、侧边栏、系统设置和云数据库登记统一来自系统数据库；
|
||
- 两个云数据库自动加载；
|
||
- 云数据库共享密码由系统数据库登录密码解锁；
|
||
- 主机、端口、库名、账号和 TLS 均由项目自动设置；
|
||
- 每台开发机可以使用自己的 `APP_KEY`，禁止复制生产环境或其他开发者的 `APP_KEY`；
|
||
- 不需要在本机填写 `DB_JIANSUN_*` 或 `DB_OPERATIONS_REPLICA_*`。
|
||
|
||
系统数据库保存云数据库配置、活跃查询登记、数据字典和生产共享查询快照，但不会自己执行 SQL，也不是 SQL Server 网络代理。本地开发环境从系统数据库自动读取两套上游连接资料，然后由本地应用直接执行代码中的固定只读查询；生产环境继续由后台刷新进程生成共享快照。
|
||
|
||
新人不填写上游地址、账号、密码、TLS、证书、白名单、VPN 或 SSH 隧道配置。连接资料统一由系统自动解析；若本机网络确实不能到达某个上游，Codex 必须直接报告失败发生在 DNS、TCP、TLS、登录、数据库、Schema 还是业务查询阶段，不能把网络问题说成代码范围或共享快照问题。
|
||
|
||
## 第一次启动
|
||
|
||
前提：Docker Desktop 已启动。
|
||
|
||
下面的命令由 Codex 在 Git Bash、WSL、macOS 或 Linux 终端中执行，不交给新人：
|
||
|
||
```bash
|
||
bash deploy/local-init.sh --build
|
||
```
|
||
|
||
脚本会：
|
||
|
||
1. 在 `runtime/.env` 不存在时生成仅供本机使用的环境配置和随机 `APP_KEY`；
|
||
2. 首次构建并启动应用和临时 MySQL；
|
||
3. 随机生成临时管理员密码，只写入被 Git 忽略的本机私有文件；
|
||
4. 自动补齐本机临时引导库的新结构，不要求开发者执行迁移命令；
|
||
5. 检查安装状态、数据库连接、运行目录和登录页；
|
||
6. 提示下一步配置系统数据库。
|
||
|
||
首次临时登录凭据保存在 `runtime/bootstrap-credentials.env`，仅用于登录本机引导库。
|
||
|
||
这个账号只存在于本机临时数据库中。系统数据库切换完成后，请使用系统数据库里属于自己的账号登录，不要继续把临时账号当作团队共享账号。
|
||
|
||
初始化中断后，Codex 直接重新执行 `bash deploy/local-init.sh`，脚本会复用已有镜像并从数据库初始化阶段继续。只有依赖、Dockerfile 或构建资源发生变化时才使用 `--build`；确认只启动现有镜像时可使用 `--skip-build`。
|
||
|
||
拉取新代码后再次运行该脚本时，本机临时引导库会自动更新；连接团队共享系统数据库后，这项自动更新会安全跳过。普通开发者任何时候都不需要执行 `php artisan migrate`，也不得对团队共享系统数据库自行迁移。
|
||
|
||
## 配置系统数据库
|
||
|
||
1. 打开 `http://127.0.0.1:18088/auth/login`。
|
||
2. 首次使用临时账号登录。
|
||
3. 打开“系统设置 → 数据库管理”。
|
||
4. 在固定的“系统数据库”区域点击“连接”。
|
||
5. 只填写负责人提供的系统数据库密码。
|
||
6. 点击“连接系统数据库”。
|
||
7. 程序只验证密码能解锁固定配置、数据库可以连接且基础系统表存在，然后自动完成切换；不会再用迁移版本、管理员权限映射或云数据库状态阻止连接。
|
||
8. 成功后临时登录 Session 会立即失效，请使用系统数据库中属于自己的正式账号重新登录。
|
||
9. 返回数据库管理页面，确认状态为“共享 · 已连接”，并确认两个云数据库已经自动出现。
|
||
|
||
连接地址、账号和传输加密由项目内的团队固定连接资料自动设置。普通开发者不填写、不修改，也不需要理解证书或 CA 路径。密码错误会在当前页面明确提示；共享数据库暂时不可达时仍保留本机引导库，不会进入 500 页面。
|
||
|
||
保存系统数据库时，程序会自动设置：
|
||
|
||
```dotenv
|
||
UPSTREAM_STORED_CONFIG_ENABLED=true
|
||
UPSTREAM_LOCAL_CONFIG_ENABLED=false
|
||
SYSTEM_DATABASE_MODE=shared
|
||
```
|
||
|
||
不要手工把 `DB_HOST` 改回 `mysql`，否则会重新使用互不相干的本机用户和配置。
|
||
|
||
## 验收共享云数据库
|
||
|
||
仅看到两条云数据库记录并不代表业务读取已经成功。系统数据库连接后，Codex 必须在应用容器内自动完成：
|
||
|
||
1. 确认当前是 `shared` 系统数据库模式，本机上游覆盖关闭；
|
||
2. 确认两条共享连接资料均能由 `UpstreamSourceRegistry` 正确解析；
|
||
3. 分别完成数据库连接和 `SELECT 1`；
|
||
4. 分别对至少一个真实业务表或视图执行限定字段、限定行数的只读查询；
|
||
5. 同步或读取两套来源的数据字典；
|
||
6. 逐个来源报告来源标识、数据库和 Schema、验证对象、读取字段、返回行数、耗时、`direct` 状态和失败阶段。
|
||
|
||
不能用端口连通、共享密码可解密、数据字典存在或 `SELECT 1` 成功代替真实业务行验收；也不能因为缺少 Repository、`scope` 或生产快照，就判断本地开发无法读取上游。
|
||
|
||
## 需要尚未缓存的新表或字段
|
||
|
||
系统不会自动复制两个上游数据库的全部表。开发者需要新表或字段时，由 Codex 按下面流程完成：
|
||
|
||
1. 从共享数据字典确认来源、表或视图和字段；目录缺失或过期时由 Codex 执行 `upstream:schema:sync`；
|
||
2. 在本地通过 `UpstreamReadOnlyQueryFactory` 执行一次限定字段、限定行数的真实只读探索查询，不需要先有 Repository、`scope` 或生产快照；
|
||
3. 确认业务目的、字段含义、筛选条件、排序方式、最大返回量、公司/权限范围及建议缓存时间；
|
||
4. 在任务分支中通过 `UpstreamReadOnlyQuery` 实现固定、参数化的只读查询，页面只调用 Repository；
|
||
5. 为生产查询定义稳定 `scope`，通过 `UpstreamQueryCache` 读取，并在对应 `UpstreamSnapshotRefresher` 中登记同一范围；
|
||
6. 完成自动测试和本地真实只读验收后合并到 `main`；
|
||
7. 生产部署后生成首份共享快照，再验证第二个应用实例复用该快照。
|
||
|
||
系统数据库中只保存受控查询的标识、参数、访问范围和结果，不保存可执行的任意 SQL。需要调整查询时必须修改代码并重新走合并、部署和验收流程。
|
||
|
||
## 常用命令
|
||
|
||
本节只供 Codex 排错和验收使用，新人不需要手工执行。
|
||
|
||
所有 Laravel 命令都必须使用 `-u www-data`。省略后 Docker 会默认使用 `root`，可能生成网页进程无法写入的缓存、日志或系统数据库备份，造成“测试通过但页面 500”。
|
||
|
||
```bash
|
||
# 查看状态
|
||
docker compose -f docker-compose.local.yml ps
|
||
|
||
# 查看应用日志
|
||
docker compose -f docker-compose.local.yml logs -f app
|
||
|
||
# 查看共享快照后台进程
|
||
docker compose -f docker-compose.local.yml logs -f snapshot_worker
|
||
|
||
# 重启应用
|
||
docker compose -f docker-compose.local.yml restart app
|
||
|
||
# 清理应用缓存
|
||
docker compose -f docker-compose.local.yml exec -u www-data app php artisan optimize:clear
|
||
|
||
# 检查应用是否真正就绪
|
||
docker compose -f docker-compose.local.yml exec -u www-data app php artisan app:ready
|
||
|
||
# 运行测试（首次需使用 local-init.sh --build 构建开发依赖）
|
||
docker compose -f docker-compose.local.yml exec -u www-data app php artisan test --do-not-cache-result
|
||
|
||
# 停止容器，但保留本地数据
|
||
docker compose -f docker-compose.local.yml stop
|
||
|
||
# 再次启动
|
||
docker compose -f docker-compose.local.yml start
|
||
```
|
||
|
||
不要执行 `docker compose down -v`、删除数据库卷或强制迁移。确需重置本地临时库时，先确认不会影响当前系统数据库配置并找负责人或 Codex处理。
|
||
|
||
## 修改后的生效方式
|
||
|
||
- PHP、配置、模块、页面模板和路由目录已经挂载到容器，通常清理缓存或重启应用即可；
|
||
- Composer 依赖、前端依赖、Dockerfile 或构建资源发生变化时，执行 `bash deploy/local-init.sh --build`；
|
||
- 修改 `runtime/.env` 后，执行：
|
||
|
||
```bash
|
||
docker compose -f docker-compose.local.yml restart app
|
||
docker compose -f docker-compose.local.yml exec -u www-data app php artisan optimize:clear
|
||
```
|
||
|
||
## 相关文档
|
||
|
||
- 团队规则：`AGENTS.md`
|
||
- 开发和正式发布：`docs/开发与部署SOP.md`
|
||
- 上游业务接入：`docs/ecommerce-finance-development.md`
|
||
|
||
真实密码、数据库连接串、Token、SSH 私钥和 `runtime/.env` 均不得提交到 Git。
|