WuYongJie/CaiWuXiTong
1
0
Fork 0
Code Issues Pull Requests 2 Packages Projects Releases Wiki Activity
CaiWuXiTong/docs/新电脑开发接续指南.md

9.9 KiB
Raw Permalink Blame History

新电脑开发接续指南

本指南用于在另一台 Windows 电脑上继续开发 CaiWuXiTong。仓库代码、开发环境和团队系统数据库配置分开管理：新电脑只需要重新克隆代码、启动本机 Docker 环境，并在页面中完成一次团队系统数据库接入。

0. 仓库、Git 与线上服务器

Git 仓库

  • 远程仓库：http://git.1080p.hk/WuYongJie/CaiWuXiTong.git
  • Git 登录账号：lunanting
  • 当前提交身份：404877757@qq.com（只影响提交署名，不等同于登录账号）
  • Git 凭据应交给 Git Credential Manager 保存，不要把用户名和密码拼进 URL、脚本或命令历史。
  • 本机私密附录位置：runtime/private/新电脑开发接续私密信息.md。该目录已被 .gitignore 忽略，不会随仓库推送；需要带到另一台电脑时，请通过加密文件传输或密码管理器转交。

新电脑首次配置 Git Credential Manager：

git config --global credential.helper manager
git clone http://git.1080p.hk/WuYongJie/CaiWuXiTong.git

提示输入凭据时，用户名填写 lunanting，密码从私密附录或密码管理器获取。不要使用服务器 root 密码作为 Git 密码。

线上地址

服务器 SSH

  • 服务器：218.93.190.75
  • 用户：root
  • 首次连接可使用私密附录中的临时密码：
ssh root@218.93.190.75

建议在新电脑生成自己的 Ed25519 密钥，不要复制其他电脑的私钥：

ssh-keygen -t ed25519 -f "$env:USERPROFILE\.ssh\caiwuxitong_deploy_ed25519"
$pub = (Get-Content "$env:USERPROFILE\.ssh\caiwuxitong_deploy_ed25519.pub" -Raw).Trim()
ssh root@218.93.190.75 "umask 077; mkdir -p ~/.ssh; chmod 700 ~/.ssh; grep -qxF '$pub' ~/.ssh/authorized_keys 2>/dev/null || printf '%s\n' '$pub' >> ~/.ssh/authorized_keys; chmod 600 ~/.ssh/authorized_keys"

上面的最后一条命令会提示输入一次服务器密码；不要把密码直接写在命令行。验证密钥登录：

ssh -i "$env:USERPROFILE\.ssh\caiwuxitong_deploy_ed25519" -o BatchMode=yes root@218.93.190.75 "hostname"

正式发布只能由 Codex 按 SOP 执行，服务器不构建源码。新电脑具备 Docker Desktop、Git 和密钥后，发布命令为：

git switch main
git pull --ff-only origin main
.\scripts\deploy-from-workstation.ps1 `
  -Server 218.93.190.75 `
  -KeyPath "$env:USERPROFILE\.ssh\caiwuxitong_deploy_ed25519"

首次初始化全新服务器才使用 -BootstrapServer；当前生产服务器已经初始化，禁止重复执行。脚本发现新增数据库迁移时会停止，必须先取得负责人授权并完成备份后再使用 -AllowMigrations。

先看这几条边界

  • Git 认证使用项目负责人分配的 Git 账号或令牌；不要把服务器 root 密码当作 Git 密码，也不要把凭据写进仓库地址、脚本或受版本控制的 Markdown。密码只放在被 Git 忽略的私密附录或密码管理器中。
  • 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 的凭据管理器保存，不要写入命令行历史。

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

已有本地副本时，从仓库目录执行：

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 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。
  2. 从本机私有文件 runtime/bootstrap-credentials.env 读取临时账号，仅用于第一次登录；不要复制、提交或发到聊天工具。
  3. 进入“系统设置 → 数据库管理 → 系统数据库”。
  4. 只输入负责人提供的系统数据库密码，点击“连接系统数据库”。不填写主机、端口、库名、账号、TLS、证书或任何上游数据库密码。
  5. 连接成功后临时 Session 会失效，使用团队系统数据库中属于自己的正式账号重新登录。
  6. 返回“数据库管理”，确认系统数据库显示为“共享 · 已连接”，并检查已登记的上游来源和业务镜像状态。

每台电脑只需完成一次上述接入。连接资料、上游账号和共享密码由系统数据库加密保存；不要从其他电脑复制 .env 或修改 DB_JIANSUN_、DB_OPERATIONS_REPLICA_。

5. 基本验收（由 Codex 执行）

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. 开始新的开发任务

从最新主线创建任务分支：

git switch main
git pull --ff-only origin main
git switch -c feature/<用户名>-<任务名>
git push -u origin feature/<用户名>-<任务名>

任务开始前阅读 团队协作说明。涉及共享路由、Repository、数据表、上游来源、权限或公共组件时，先按项目规则完成碰撞检查，再开始大量修改。不要复用已经存在的其他人的任务分支。

常用的本地验证命令如下，均由 Codex 在容器内以 www-data 身份执行：

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. 日常启动、停止和排错

# 查看容器
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 与 开发与部署 SOP。

8. 文档阅读顺序

建议按以下顺序阅读：

  1. 本文：新电脑接续和本地启动；
  2. AGENTS.md：团队规则和安全边界；
  3. LOCAL_DEPLOY.md：本地环境细节与排错；
  4. docs/开发与部署SOP.md：协作、上游、镜像和生产发布；
  5. 与当前任务对应的业务需求、上游接入或视觉文档。

完整文档清单见 docs/README.md。