diff --git a/AGENTS.md b/AGENTS.md index 2dd36f51..98b8bec0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -65,10 +65,10 @@ ## 8. 构建与生产部署 - 普通代码发布由任务 Codex 在完成验证与合并后直接执行,不要求用户再次说“部署、上线”;用户明确要求仅本地开发、仅审查或暂不上线时遵循其范围。正式发布只使用已合并的最新 `main`。 -- Windows 开发机统一使用 `scripts/deploy-from-workstation.ps1`。服务器只运行开发机已构建的 `caiwu_akaunting:` 镜像,禁止在服务器执行 Composer、npm 或 Docker 构建。 +- Windows 开发机统一使用 `scripts/deploy-from-workstation.ps1`,macOS 开发机使用 `bash scripts/deploy-from-mac.sh`;两者流程一致(本机构建前端与镜像、迁移拦截、增量推送服务器本机 Registry、激活与健康检查、双版本保留)。服务器只运行开发机已构建的 `caiwu_akaunting:` 镜像,禁止在服务器执行 Composer、npm 或 Docker 构建。 - 新人只需表达部署需求;Codex 使用默认生产入口运行脚本。首次通过本机窗口提供一次服务器密码后,加密保存在本人电脑供后续自动使用,不要求新人准备私钥、执行命令或每次重输密码。已有私钥认证仍兼容。 - 当前生产入口为 `https://caiwu.jiansuntuzhi.cn:8442`;公网仍只使用 `8442`,日常发布不得改成无端口地址。 -- 发布脚本检测到新增数据库迁移时,由 Codex 核对全部待执行迁移。仅涉及本任务共享镜像建表、字段、索引和同步登记的迁移,完成备份后自主使用 `-AllowMigrations`;其他迁移仍按第 6 节确认授权。不能因需要迁移开关就把镜像接入停给负责人。 +- 发布脚本检测到新增数据库迁移时,由 Codex 核对全部待执行迁移。仅涉及本任务共享镜像建表、字段、索引和同步登记的迁移,完成备份后自主使用 `-AllowMigrations`(macOS 为 `--allow-migrations`);其他迁移仍按第 6 节确认授权。不能因需要迁移开关就把镜像接入停给负责人。 - 容器内 Laravel 命令使用 `www-data`。发布后只需确认部署 SHA、应用容器健康、受影响的真实页面/接口、迁移是否执行,以及当前和上一版镜像可回滚。 - 程序静态资源随应用镜像同源发布;七牛只存用户上传的业务图片、票据和附件。 - 只有本地初始化、服务器维护、生产发布或数据库迁移任务需要读取 `docs/开发与部署SOP.md` 的对应章节;普通功能开发无需加载整份 SOP。 diff --git a/docs/开发与部署SOP.md b/docs/开发与部署SOP.md index 4ed1039c..9ea96b65 100644 --- a/docs/开发与部署SOP.md +++ b/docs/开发与部署SOP.md @@ -39,7 +39,7 @@ 2. 在 Docker Desktop 的 `Settings -> Resources -> Advanced` 中: - Docker 虚拟磁盘上限建议 60GB; - Windows 磁盘至少保留 15GB 可用空间。 -3. 首次部署仅需在本机密码窗口输入一次服务器密码,之后 Codex 自动复用本机加密保存的登录信息;不要求新人生成、配置或管理私钥。密码使用 Windows 当前用户绑定的 DPAPI 加密,保存在 `%LOCALAPPDATA%\CaiWuXiTong\deploy-credentials`,不进入仓库或日志。已有私钥的机器仍可选传 `-KeyPath`。 +3. 首次部署仅需在本机密码窗口输入一次服务器密码,之后 Codex 自动复用本机加密保存的登录信息;不要求新人生成、配置或管理私钥。Windows 上密码使用当前用户绑定的 DPAPI 加密,保存在 `%LOCALAPPDATA%\CaiWuXiTong\deploy-credentials`;macOS 上保存在系统钥匙串(服务名 `CaiWuXiTong-deploy`)。两者都不进入仓库或日志。已有私钥的机器仍可选传 `-KeyPath`(macOS 为 `--key`)。 4. 只使用仓库里的发布脚本。不要自行执行 `docker system prune -a`,也不要重置 Docker Desktop。 Codex 已有用户提供的密码时可通过 `-Password` 的 `SecureString` 参数直接使用并保存,无需用户再输入;不要把明文写进命令参数或日志。密码变更时由 Codex 使用 `-UpdatePassword` 更新本机登录信息。部署结束保留加密凭据,下次自动使用。 @@ -76,6 +76,12 @@ Codex 已有用户提供的密码时可通过 `-Password` 的 `SecureString` 参 -BootstrapServer ``` +macOS 开发机使用同一套流程的脚本: + +```bash +bash scripts/deploy-from-mac.sh --bootstrap-server +``` + 初始化脚本会: - 使用服务器现有 Ubuntu 安全更新源安装并启动 Docker 与 Compose; @@ -102,6 +108,15 @@ git pull --ff-only .\scripts\deploy-from-workstation.ps1 ``` +macOS 开发机使用同一套流程的脚本: + +```bash +git switch main +git pull --ff-only + +bash scripts/deploy-from-mac.sh +``` + 脚本自动完成: 1. 检查分支和未提交改动; @@ -124,7 +139,7 @@ git pull --ff-only 第 6 步默认用项目专用 `regctl`(未签名)把 BuildKit 原生 OCI 分层包推入服务器本机 Registry。少数开发机的 360 安全卫士、金山毒霸等安全软件会拦截未签名程序,表现为 `regctl-v0.11.5.exe` 启动即报“拒绝访问”。 - 脚本会自动降级:regctl 无法运行或连续上传失败时,改用 `docker save` 全量包经 `scp` 上传,在服务器上 `docker load`、推入本机 Registry,再执行同一个 `activate-incremental-release.sh`(回滚、健康检查、双版本保留和旧层回收逻辑不变)。降级只增加传输量,功能与发布结果一致。 -- 也可以在受拦截的开发机上显式跳过 regctl:`.\scripts\deploy-from-workstation.ps1 -SkipRegctl`。 +- 也可以在受拦截的开发机上显式跳过 regctl:`.\scripts\deploy-from-workstation.ps1 -SkipRegctl`(macOS 为 `bash scripts/deploy-from-mac.sh --skip-regctl`)。 - 建议在这类开发机上把 `%LOCALAPPDATA%\CaiWuXiTong\tools` 加入安全软件信任区,以恢复只上传变化层的增量方式。 ### 5.2 程序资源与业务文件的固定边界 @@ -148,6 +163,12 @@ Codex 先核对全部待执行迁移,并准备受影响数据的备份与回 -AllowMigrations ``` +macOS 上对应命令: + +```bash +bash scripts/deploy-from-mac.sh --allow-migrations +``` + 应用镜像回滚不能自动撤销数据库结构变更;Codex 必须为本次迁移保留对应的数据备份和恢复路径。 ## 7. 测试分支发布 @@ -158,6 +179,8 @@ Codex 先核对全部待执行迁移,并准备受影响数据的备份与回 -AllowNonMain ``` +macOS 上对应参数为 `--allow-non-main`。 + 测试完成后仍要回到 `main` 再正式发布,不能把测试分支当长期生产版本。 ## 8. 多上游财务数据库同步 diff --git a/scripts/build-frontend.sh b/scripts/build-frontend.sh index 218ee318..a583cebd 100755 --- a/scripts/build-frontend.sh +++ b/scripts/build-frontend.sh @@ -242,7 +242,9 @@ restore_tracked_css() { if [ "$PUBLISH_LOCAL" -eq 0 ] && [ -n "$tracked_css_backup" ] && [ -f "$tracked_css_backup" ]; then cp "$tracked_css_backup" "$tracked_css" fi - [ -n "$tracked_css_backup" ] && rm -f "$tracked_css_backup" + if [ -n "$tracked_css_backup" ]; then + rm -f "$tracked_css_backup" + fi } trap restore_tracked_css EXIT diff --git a/scripts/deploy-from-mac.sh b/scripts/deploy-from-mac.sh index 66fd06eb..96f93d29 100755 --- a/scripts/deploy-from-mac.sh +++ b/scripts/deploy-from-mac.sh @@ -16,6 +16,7 @@ # --configure-dingtalk-callback # --allow-non-main 允许非 main 分支(测试用) # --allow-migrations 允许执行待办数据库迁移(需先按 AGENTS.md 核对) +# --skip-regctl 跳过 regctl,直接用 docker 直传镜像 # --keep-images <数量> 默认 2 # --app-version <版本> 默认 3.1.15 # @@ -38,6 +39,7 @@ bootstrap_server=0 configure_dingtalk_callback=0 allow_non_main=0 allow_migrations=0 +skip_regctl=0 app_version='3.1.15' while [ "$#" -gt 0 ]; do @@ -60,6 +62,7 @@ while [ "$#" -gt 0 ]; do --configure-dingtalk-callback) configure_dingtalk_callback=1 ;; --allow-non-main) allow_non_main=1 ;; --allow-migrations) allow_migrations=1 ;; + --skip-regctl) skip_regctl=1 ;; -h|--help) sed -n '2,20p' "$0"; exit 0 ;; *) echo "未知参数:$1" >&2; exit 2 ;; esac @@ -212,7 +215,7 @@ get_regctl_path() { asset='regctl-darwin-amd64' expected_hash='c132fdddda68b9c7584ac19f3b40cd17f71916c2bca8182270ebe65b55198a12' ;; - *) fail "不支持的 macOS 架构:$(uname -m)" ;; + *) echo "不支持的 macOS 架构:$(uname -m)" >&2; return 1 ;; esac path="$tool_root/regctl-$regctl_version" @@ -225,10 +228,15 @@ get_regctl_path() { fi local download="$path.download" - curl -fsSL -o "$download" "https://github.com/regclient/regclient/releases/download/$regctl_version/$asset" + if ! curl -fsSL --retry 3 --retry-delay 2 -o "$download" \ + "https://github.com/regclient/regclient/releases/download/$regctl_version/$asset"; then + echo 'regctl 下载失败。' >&2 + return 1 + fi if [ "$(sha256_file "$download")" != "$expected_hash" ]; then rm -f "$download" - fail 'regctl 校验失败。' + echo 'regctl 校验失败。' >&2 + return 1 fi mv "$download" "$path" chmod +x "$path" @@ -253,7 +261,8 @@ PY return fi done - fail '找不到可用的本机端口。' + echo '找不到可用的本机端口。' >&2 + return 1 } start_registry_tunnel() { @@ -267,7 +276,9 @@ start_registry_tunnel() { local attempt=1 while [ "$attempt" -le 20 ]; do if ! kill -0 "$tunnel_pid" >/dev/null 2>&1; then - fail 'SSH 增量传输隧道启动失败。' + tunnel_pid='' + echo 'SSH 增量传输隧道启动失败。' >&2 + return 1 fi if curl --fail --silent --show-error --max-time 1 "http://127.0.0.1:${local_port}/v2/" >/dev/null 2>&1; then return 0 @@ -276,7 +287,8 @@ start_registry_tunnel() { attempt=$((attempt + 1)) done - fail 'SSH 隧道已建立,但无法访问服务器本机 Registry。' + echo 'SSH 隧道已建立,但无法访问服务器本机 Registry。' >&2 + return 1 } stop_registry_tunnel() { @@ -325,9 +337,13 @@ remove_old_project_images() { while IFS= read -r candidate; do [ -n "$candidate" ] || continue - [ "$candidate" = ':' ] && continue + if [ "$candidate" = ':' ]; then + continue + fi case " $kept " in *" $candidate "*) continue ;; esac - [ "$(printf '%s\n' $kept | wc -l | tr -d ' ')" -ge "$keep_images" ] && break + if [ "$(printf '%s\n' $kept | wc -l | tr -d ' ')" -ge "$keep_images" ]; then + break + fi kept="$kept $candidate" done </dev/null 2>&1 || true ;; @@ -485,7 +503,9 @@ ssh "${ssh_options[@]}" "$ssh_target" "docker version >/dev/null && docker compo ensure_qiniu_storage_runtime migration_flag=0 -[ "$allow_migrations" -eq 1 ] && migration_flag=1 +if [ "$allow_migrations" -eq 1 ]; then + migration_flag=1 +fi scp_to_remote \ "$repo_root/compose.jiangling.yml" \ @@ -537,35 +557,64 @@ else --file deploy/Dockerfile \ . || fail '导出稳定分层的 OCI 应用镜像失败。' - regctl_path="$(get_regctl_path)" - local_registry_port="$(pick_free_port)" - start_registry_tunnel "$local_registry_port" - registry_image="127.0.0.1:${local_registry_port}/caiwuxitong/app:$image_tag" server_registry_image="$image_prefix:$image_tag" before_bytes="$(ssh "${ssh_options[@]}" "$ssh_target" "du -sb /var/lib/docker-registry 2>/dev/null | cut -f1" | tr -dc '0-9')" : "${before_bytes:=0}" upload_start="$(date +%s)" upload_ok=0 - upload_attempt=1 - while [ "$upload_attempt" -le 2 ]; do - if [ "$upload_attempt" -gt 1 ]; then - stop_registry_tunnel - local_registry_port="$(pick_free_port)" - start_registry_tunnel "$local_registry_port" - registry_image="127.0.0.1:${local_registry_port}/caiwuxitong/app:$image_tag" + + if [ "$skip_regctl" -eq 0 ]; then + if regctl_path="$(get_regctl_path)"; then + if local_registry_port="$(pick_free_port)" && start_registry_tunnel "$local_registry_port"; then + registry_image="127.0.0.1:${local_registry_port}/caiwuxitong/app:$image_tag" + upload_attempt=1 + while [ "$upload_attempt" -le 2 ]; do + if [ "$upload_attempt" -gt 1 ]; then + stop_registry_tunnel + local_registry_port="$(pick_free_port)" || break + start_registry_tunnel "$local_registry_port" || break + registry_image="127.0.0.1:${local_registry_port}/caiwuxitong/app:$image_tag" + fi + + if "$regctl_path" --host "reg=127.0.0.1:${local_registry_port},tls=disabled" image import "$registry_image" "$local_tar"; then + upload_ok=1 + break + fi + + if [ "$upload_attempt" -eq 1 ]; then + log '增量镜像隧道在上传期间中断,正在重新建立隧道并重试一次。' + fi + upload_attempt=$((upload_attempt + 1)) + done + fi + else + log 'regctl 无法准备(本机安全软件可能拦截了未签名程序)。' + fi + else + log '已指定 --skip-regctl:跳过 regctl,直接用 docker 直传镜像。' + fi + + stop_registry_tunnel + + if [ "$upload_ok" -eq 0 ]; then + if [ "$skip_regctl" -eq 0 ]; then + log '改用 docker 直传方式上传镜像(与 regctl 增量导入等效,只是传输完整镜像包)。' fi - if "$regctl_path" --host "reg=127.0.0.1:${local_registry_port},tls=disabled" image import "$registry_image" "$local_tar"; then - upload_ok=1 - break - fi + rm -f "$local_tar" + docker save --output "$local_tar" "$full_image" || fail '导出应用镜像失败。' + gzip -1 -c "$local_tar" > "$local_archive" + rm -f "$local_tar" + log "docker 直传镜像包:$(du -m "$local_archive" | awk '{print $1}') MiB" + + scp_to_remote "$local_archive" "${ssh_target}:$remote_archive" || fail '上传镜像失败。' + ssh "${ssh_options[@]}" "$ssh_target" \ + "gunzip -cf '$remote_archive' | docker load && docker tag '$full_image' '$server_registry_image' && docker push '$server_registry_image'" \ + || fail '服务器加载镜像或推入本机 Registry 失败。' + upload_ok=1 + fi - if [ "$upload_attempt" -eq 1 ]; then - log '增量镜像隧道在上传期间中断,正在重新建立隧道并重试一次。' - fi - upload_attempt=$((upload_attempt + 1)) - done [ "$upload_ok" -eq 1 ] || fail '增量镜像层上传失败。' upload_seconds=$(( $(date +%s) - upload_start ))