147 lines
7.4 KiB
Markdown
147 lines
7.4 KiB
Markdown
# 新电脑开发接续指南
|
||
|
||
本指南用于在另一台 Windows 电脑上继续开发 CaiWuXiTong。仓库代码、开发环境和团队系统数据库配置分开管理：新电脑只需要重新克隆代码、启动本机 Docker 环境，并在页面中完成一次团队系统数据库接入。
|
||
|
||
## 先看这几条边界
|
||
|
||
- Git 认证使用项目负责人分配的 Git 账号或令牌；不要把服务器 root 密码当作 Git 密码，也不要把凭据写进仓库地址、脚本或 Markdown。
|
||
- main 是稳定主线。开发任务从最新 main 创建独立的 feature/... 或 fix/... 分支，不直接在 main 上开发。
|
||
- 不要复制其他电脑的 runtime/.env、APP_KEY、runtime/bootstrap-credentials.env、数据库卷、SSH 私钥或生产配置。每台开发机使用自己的本地配置和密钥。
|
||
- 不要对团队共享系统数据库执行 php artisan migrate，不要执行 docker compose down -v，也不要删除 Docker 数据卷。
|
||
- 新人通常只需要启动 Docker Desktop 并在网页输入负责人提供的系统数据库密码；仓库拉取、初始化、缓存、容器和排错命令交给 Codex 执行。
|
||
|
||
## 1. 准备 Windows 环境
|
||
|
||
安装并启动以下软件：
|
||
|
||
1. Git（建议启用 Git Credential Manager）；
|
||
2. Docker Desktop，使用 WSL2 后端；
|
||
3. Git Bash 或 WSL，用于执行项目中的 Bash 初始化脚本。
|
||
|
||
Docker Desktop 启动后确认没有暂停或报错。磁盘空间不足会导致镜像构建失败，建议为 Docker 虚拟磁盘预留约 60GB 上限，并为 Windows 保留至少 15GB 可用空间。
|
||
|
||
## 2. 克隆并拉取最新代码
|
||
|
||
在 Git Bash 或 WSL 中执行。首次克隆时，Git 可能会提示输入项目 Git 账号或令牌；凭据只交给 Git 的凭据管理器保存，不要写入命令行历史。
|
||
|
||
~~~bash
|
||
cd /c/Users/<你的用户名>/Documents
|
||
git clone http://git.1080p.hk/WuYongJie/CaiWuXiTong.git
|
||
cd CaiWuXiTong
|
||
git fetch origin --prune
|
||
git switch main
|
||
git pull --ff-only origin main
|
||
git status --short --branch
|
||
~~~
|
||
|
||
已有本地副本时，从仓库目录执行：
|
||
|
||
~~~bash
|
||
git status --short --branch
|
||
git fetch origin --prune
|
||
git switch main
|
||
git pull --ff-only origin main
|
||
git rev-list --left-right --count HEAD...origin/main
|
||
~~~
|
||
|
||
最后一条命令显示 0 0，表示本地 main 与远程 main 已同步。如果 git status 显示无法解释的改动，先停止并保留现场，不要用 reset --hard 或 clean -fd 覆盖它。
|
||
|
||
## 3. 启动本地环境
|
||
|
||
确保 Docker Desktop 已启动，然后在仓库根目录执行：
|
||
|
||
~~~bash
|
||
bash deploy/local-init.sh
|
||
~~~
|
||
|
||
初始化脚本会自动：
|
||
|
||
- 生成被 Git 忽略的 runtime/.env 和本机随机 APP_KEY；
|
||
- 构建或复用带有当前源码指纹的开发镜像；
|
||
- 启动应用和仅用于首次登录的本机 MySQL；
|
||
- 初始化本机临时引导库并生成临时登录凭据；
|
||
- 清理缓存、修复容器内运行目录权限并执行就绪检查。
|
||
|
||
代码、依赖、Dockerfile 或前端资源发生变化时，仍然运行同一条命令，脚本会自动判断是否需要重建。只有需要明确强制重建时才使用 bash deploy/local-init.sh --build；不要让新开发者自行判断构建参数。
|
||
|
||
## 4. 首次登录并接入团队系统数据库
|
||
|
||
1. 打开 [http://127.0.0.1:18088/auth/login](http://127.0.0.1:18088/auth/login)。
|
||
2. 从本机私有文件 runtime/bootstrap-credentials.env 读取临时账号，仅用于第一次登录；不要复制、提交或发到聊天工具。
|
||
3. 进入“系统设置 → 数据库管理 → 系统数据库”。
|
||
4. 只输入负责人提供的系统数据库密码，点击“连接系统数据库”。不填写主机、端口、库名、账号、TLS、证书或任何上游数据库密码。
|
||
5. 连接成功后临时 Session 会失效，使用团队系统数据库中属于自己的正式账号重新登录。
|
||
6. 返回“数据库管理”，确认系统数据库显示为“共享 · 已连接”，并检查已登记的上游来源和业务镜像状态。
|
||
|
||
每台电脑只需完成一次上述接入。连接资料、上游账号和共享密码由系统数据库加密保存；不要从其他电脑复制 .env 或修改 DB_JIANSUN_*、DB_OPERATIONS_REPLICA_*。
|
||
|
||
## 5. 基本验收（由 Codex 执行）
|
||
|
||
~~~bash
|
||
docker compose -f docker-compose.local.yml ps
|
||
docker compose -f docker-compose.local.yml exec -T -u www-data app php artisan app:ready
|
||
docker compose -f docker-compose.local.yml exec -T -u www-data app php artisan system-database:verify --no-ansi
|
||
~~~
|
||
|
||
app:ready 通过只表示本地应用已就绪；system-database:verify 通过才表示团队系统数据库接入成功。首次接入尚未完成时，初始化脚本会保留本机引导库并提示在网页输入一次密码，不应把这种状态当成代码或数据为空。
|
||
|
||
## 6. 开始新的开发任务
|
||
|
||
从最新主线创建任务分支：
|
||
|
||
~~~bash
|
||
git switch main
|
||
git pull --ff-only origin main
|
||
git switch -c feature/<用户名>-<任务名>
|
||
git push -u origin feature/<用户名>-<任务名>
|
||
~~~
|
||
|
||
任务开始前阅读 [团队协作说明](team-collaboration.md)。涉及共享路由、Repository、数据表、上游来源、权限或公共组件时，先按项目规则完成碰撞检查，再开始大量修改。不要复用已经存在的其他人的任务分支。
|
||
|
||
常用的本地验证命令如下，均由 Codex 在容器内以 www-data 身份执行：
|
||
|
||
~~~bash
|
||
docker compose -f docker-compose.local.yml exec -T -u www-data app php artisan optimize:clear
|
||
docker compose -f docker-compose.local.yml exec -T -u www-data app php artisan test --do-not-cache-result
|
||
~~~
|
||
|
||
完成修改后提交当前任务文件并推送分支；不要把 runtime/、.env、凭据、日志、数据库文件、构建包或私钥加入提交。
|
||
|
||
## 7. 日常启动、停止和排错
|
||
|
||
~~~bash
|
||
# 查看容器
|
||
docker compose -f docker-compose.local.yml ps
|
||
|
||
# 停止但保留本地数据
|
||
docker compose -f docker-compose.local.yml stop
|
||
|
||
# 再次启动
|
||
docker compose -f docker-compose.local.yml start
|
||
|
||
# 查看应用日志
|
||
docker compose -f docker-compose.local.yml logs --tail=100 app
|
||
~~~
|
||
|
||
常见处理方式：
|
||
|
||
- Docker 未就绪：先启动 Docker Desktop，确认 WSL2 引擎正常，再重新运行 bash deploy/local-init.sh。
|
||
- 页面返回 500：先查看应用日志并执行 optimize:clear；不要直接迁移数据库或删除卷。
|
||
- 页面没有业务数据：先确认已使用正式团队账号登录，并检查共享数据库和业务镜像状态；本机临时库有数据不代表已接入团队数据。
|
||
- 拉取后代码看起来没更新：确认当前目录、git log -1 --oneline 和 git rev-list --left-right --count HEAD...origin/main，不要在未确认改动归属前覆盖文件。
|
||
- 共享数据库暂时不可达：保留现有配置并报告失败阶段（DNS、TCP、TLS、登录、数据库、Schema 或业务查询）；不要把网络故障解释成“没有数据”。
|
||
|
||
更完整的本地部署、上游接入和正式发布流程见 [LOCAL_DEPLOY.md](../LOCAL_DEPLOY.md) 与 [开发与部署 SOP](开发与部署SOP.md)。
|
||
|
||
## 8. 文档阅读顺序
|
||
|
||
建议按以下顺序阅读：
|
||
|
||
1. 本文：新电脑接续和本地启动；
|
||
2. [AGENTS.md](../AGENTS.md)：团队规则和安全边界；
|
||
3. [LOCAL_DEPLOY.md](../LOCAL_DEPLOY.md)：本地环境细节与排错；
|
||
4. [docs/开发与部署SOP.md](开发与部署SOP.md)：协作、上游、镜像和生产发布；
|
||
5. 与当前任务对应的业务需求、上游接入或视觉文档。
|
||
|
||
完整文档清单见 [docs/README.md](README.md)。
|