CaiWuXiTong 本地测试环境

本说明用于开发者在自己的电脑上启动项目。项目使用 Docker，默认访问地址为：

http://127.0.0.1:18088

先理解数据库关系

本地 Compose 中的 MySQL 只负责第一次启动，让开发者能够使用临时账号进入系统。

登录后必须在：

系统设置 → 数据库管理 → 系统数据库 → 连接

只填写负责人提供的系统数据库密码并点击“连接系统数据库”。连接成功后：

用户、侧边栏、系统设置和云数据库登记统一来自系统数据库；
两个云数据库自动加载；
云数据库共享密码由系统数据库登录密码解锁；
主机、端口、库名、账号和 TLS 均由项目自动设置；
每台开发机可以使用自己的 APP_KEY，禁止复制生产环境或其他开发者的 APP_KEY；
不需要在本机填写 DB_JIANSUN_* 或 DB_OPERATIONS_REPLICA_*。

系统数据库保存云数据库配置、活跃查询登记和共享查询快照，但不会自己执行 SQL，也不是 SQL Server 网络代理。日常开发由具备上游连通性的生产后台刷新进程读取云数据库并写回共享快照，普通开发机不需要配置白名单、VPN、SSH 隧道或本机上游凭据。

已有快照会直接返回。完全没有快照时，本机页面会先登记这次查询；如果本机网络不能访问上游，本次请求可能暂时显示不可用，但生产后台进程会在代码已经合并部署且数据范围已获准后读取该登记并生成共享快照。不得为了消除这次提示而复制其他人的 .env、APP_KEY 或数据库密码。

第一次启动

前提：Docker Desktop 已启动。

在 Git Bash、WSL、macOS 或 Linux 终端中执行：

bash deploy/local-init.sh --build

脚本会：

在 runtime/.env 不存在时生成仅供本机使用的环境配置和随机 APP_KEY；
首次构建并启动应用和临时 MySQL；
随机生成临时管理员密码，只写入被 Git 忽略的本机私有文件；
检查安装状态、数据库连接、运行目录和登录页；
提示下一步配置系统数据库。

首次临时登录凭据保存在 runtime/bootstrap-credentials.env。脚本只显示文件路径，不打印密码。不要提交、截图或转发该文件。

这个账号只存在于本机临时数据库中。系统数据库切换完成后，请使用系统数据库里属于自己的账号登录，不要继续把临时账号当作团队共享账号。

初始化中断后直接重新执行 bash deploy/local-init.sh 会复用已有镜像并从数据库初始化阶段继续。只有依赖、Dockerfile 或构建资源发生变化时才使用 --build；确认只启动现有镜像时可使用 --skip-build。

配置系统数据库

打开 http://127.0.0.1:18088/auth/login。
首次使用临时账号登录。
打开“系统设置 → 数据库管理”。
在固定的“系统数据库”区域点击“连接”。
只填写负责人提供的系统数据库密码。
点击“连接系统数据库”。
程序只验证密码能解锁固定配置、数据库可以连接且基础系统表存在，然后自动完成切换；不会再用迁移版本、管理员权限映射或云数据库状态阻止连接。
成功后临时登录 Session 会立即失效，请使用系统数据库中属于自己的正式账号重新登录。
返回数据库管理页面，确认状态为“共享 · 已连接”，并确认两个云数据库已经自动出现。

连接地址、账号和传输加密由项目内的团队固定连接资料自动设置。普通开发者不填写、不修改，也不需要理解证书或 CA 路径。密码错误会在当前页面明确提示；共享数据库暂时不可达时仍保留本机引导库，不会进入 500 页面。

保存系统数据库时，程序会自动设置：

UPSTREAM_STORED_CONFIG_ENABLED=true
UPSTREAM_LOCAL_CONFIG_ENABLED=false
SYSTEM_DATABASE_MODE=shared

不要手工把 DB_HOST 改回 mysql，否则会重新使用互不相干的本机用户和配置。

验收共享云数据库

仅看到两条云数据库记录并不代表业务读取已经成功。验收时应在应用容器内完成：

确认两条记录都显示启用；
确认共享密码可以解锁；
至少调用一个已经登记并产生共享快照的真实业务查询；
检查页面或 API 的数据状态和同步时间；
在不提供本机上游凭据、且不依赖本机直连的情况下确认结果可以重复读取。

两个上游的 SELECT 1、首次真实查询和慢查询观察属于发布验收，由具备网络连通性的生产刷新节点或获授权的诊断环境执行，不要求每位开发者在自己的电脑上重复连接。

禁止为了排错复制别人的 .env、生产 APP_KEY 或云数据库密码。

需要尚未缓存的新表或字段

系统不会自动复制两个上游数据库的全部表。开发者需要系统数据库中尚无快照的数据时，按下面流程处理：

先确认业务目的、来源标识、所需表和字段、筛选条件、排序方式、最大返回量、公司/权限范围及建议缓存时间；
在自己的任务分支中通过 UpstreamReadOnlyQuery 实现固定、参数化的只读查询，页面只能调用 Repository，不能直接拿 PDO；
为查询定义稳定的 scope，通过 UpstreamQueryCache 读取，并在对应 UpstreamSnapshotRefresher 中登记同一范围；
分支开发阶段使用脱敏 fixture 或测试替身完成页面和错误状态验证；尚未合并的查询不会被生产后台进程执行；
通过测试和代码检查后合并到 main，先部署代码，再由负责人只开放这一个精确范围，禁止使用全局 *；
首次页面请求会把查询登记到共享系统数据库，生产后台进程随后读取上游并写入首份共享快照；
再次访问应返回 fresh 或 stale，并验证另一台开发机可以读取同一快照且不会再次访问上游。

系统数据库中只保存受控查询的标识、参数、访问范围和结果，不保存可执行的任意 SQL。需要调整查询时必须修改代码并重新走合并、部署和验收流程。

常用命令

所有 Laravel 命令都必须使用 -u www-data。省略后 Docker 会默认使用 root，可能生成网页进程无法写入的缓存、日志或系统数据库备份，造成“测试通过但页面 500”。

# 查看状态
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 后，执行：

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

8.2 KiB Raw Blame History Unescape Escape