CaiWuXiTong 本地测试环境

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

http://127.0.0.1:18088

先理解数据库关系

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

登录后必须在：

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

填写负责人提供的“财务系统配置数据库”参数并点击“测试并保存”。保存成功后：

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

系统数据库只保存配置，不代理 SQL Server 网络。开发机仍需能够直接访问对应云数据库；如果共享配置可以解锁，但 SELECT 1 失败，再检查当前网络、白名单、VPN或受限隧道。

第一次启动

前提：Docker Desktop 已启动。

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

bash deploy/local-init.sh

脚本会：

在 runtime/.env 不存在时生成仅供本机使用的环境配置和随机 APP_KEY；
构建并启动应用和临时 MySQL；
初始化临时管理员；
检查登录页是否可以访问；
提示下一步配置系统数据库。

首次临时登录：

邮箱：local-bootstrap@caiwu.test
密码：LocalOnly-18088!

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

配置系统数据库

打开 http://127.0.0.1:18088/auth/login。
首次使用临时账号登录。
打开“系统设置 → 数据库管理”。
在固定的“系统数据库”区域点击“修改连接”。
填写负责人提供的主机、端口、数据库名、账号、密码和 TLS 设置。
点击“测试并保存”。
返回数据库管理页面，确认两个云数据库已经自动出现。
退出临时账号，使用系统数据库中属于自己的账号重新登录。

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

UPSTREAM_STORED_CONFIG_ENABLED=true
UPSTREAM_LOCAL_CONFIG_ENABLED=false

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

验收共享云数据库

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

确认两条记录都显示启用；
确认共享密码可以解锁；
分别执行受控的只读 SELECT 1；
至少验证一个已登记的真实业务查询；
检查页面或 API 的数据状态和同步时间。

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

常用命令

# 查看状态
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 restart app

# 清理应用缓存
docker compose -f docker-compose.local.yml exec app php artisan optimize:clear

# 停止容器，但保留本地数据
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；
修改 runtime/.env 后，执行：

docker compose -f docker-compose.local.yml restart app
docker compose -f docker-compose.local.yml exec app php artisan optimize:clear

4.4 KiB Raw Blame History Unescape Escape