From afb959f02a7f1d02ab775c6be9d6179c742e0543 Mon Sep 17 00:00:00 2001 From: root Date: Thu, 29 Oct 2026 21:12:12 +0800 Subject: [PATCH] docs: align managed deployment with dev branch workflow --- .gitea/workflows/main.yml | 3 --- docs/deployment.md | 9 +++++---- docs/deployment.zh-CN.md | 9 +++++---- 3 files changed, 10 insertions(+), 11 deletions(-) diff --git a/.gitea/workflows/main.yml b/.gitea/workflows/main.yml index 37e2114..65f87dd 100644 --- a/.gitea/workflows/main.yml +++ b/.gitea/workflows/main.yml @@ -63,9 +63,6 @@ jobs: CI_RESOURCE_LABEL: io.rawmark.ci.run=dev-${{ gitea.run_id }}-${{ gitea.run_attempt }} TEMP_IMAGE: rawmark-ci:${{ gitea.sha }}-${{ gitea.run_id }}-${{ gitea.run_attempt }} DOCKER_CONFIG: /tmp/rawmark-docker-auth - outputs: - image: ${{ steps.publish.outputs.image }} - version: ${{ steps.publish.outputs.version }} defaults: run: shell: sh diff --git a/docs/deployment.md b/docs/deployment.md index c7e667c..51de31b 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -163,20 +163,21 @@ The Bearer authentication upgrade requires the frontend and backend to be releas ## Managed development and production -The checked-in `deploy/compose.image.yml` is an image-only template. Development lives in `/docker/gitea/dev/RawMark`; production lives in `/docker/main/rawmark`. Copy the template to the instance directory as `compose.yml`, with a private mode-600 `.env` beside it. The container name follows `RAWMARK_PROJECT`, so the development container is `rawmark-dev`. These instances do not depend on a source checkout. Set all required values explicitly: +The checked-in `deploy/compose.image.yml` is an image-only template. Development lives in `/docker/gitea/dev/RawMark`; production lives in `/docker/main/rawmark`. Copy the template to the instance directory as `compose.yml`, with a private mode-600 `.env` beside it. Set the project and container names independently. These instances do not depend on a source checkout. Set all required values explicitly: ```dotenv RAWMARK_CHANNEL=development RAWMARK_PROJECT=rawmark-dev +RAWMARK_CONTAINER_NAME=RawMark-dev RAWMARK_BIND=127.0.0.1 RAWMARK_PORT=21001 RAWMARK_DATA_DIR=/docker/gitea/dev/RawMark/data -RAWMARK_IMAGE=git.134333.xyz/eezd/rawmark@sha256: +RAWMARK_IMAGE=git.134333.xyz/eezd/dev/rawmark@sha256: ``` -For production, use channel `production`, project `rawmark`, port 21000, `/docker/main/rawmark/data`, and `ghcr.io/eezd/rawmark@sha256:`. Preserve the current binding during migration. Create only a new development data directory with owner `65532:65532`; never recursively change existing production ownership or mount the repository example template as live storage. +For production, use channel `production`, project `rawmark`, the existing container name, port 21000, `/docker/main/rawmark/data`, and `ghcr.io/eezd/rawmark@sha256:`. Preserve the current binding during migration. Create only a new development data directory with owner `65532:65532`; never recursively change existing production ownership or mount the repository example template as live storage. -Main-push CI automatically updates development. The **Deploy production manually** Gitea workflow only accepts a version whose Gitea and GitHub releases are formal and contain identical build/release receipts and matching tags. It fixes the GHCR digest, checks current mounts and competing writers, stops only this project's old service, and backs up the whole data directory plus configuration before replacement. Backups are private and include SQLite WAL files; old images and backups are retained. +Dev-push CI automatically updates development after checks and isolated smoke tests pass. Main pushes and PRs only validate. Formal release and **Deploy production manually** Gitea workflows remain disabled during this CI migration; enabling or executing them requires a separate release plan and authorization. The prepared production workflow requires matching formal Gitea/GitHub releases and receipts, pins the GHCR digest, and backs up data and configuration before replacement. Backups are private and include SQLite WAL files; old images and backups are retained. The job records `deployment.pending.json` before replacement and `deployment.json` after health/frontend checks. If the candidate fails after accessing data, it stops the candidate and retains the backup and pending record for diagnosis; it does not automatically restore private data or run an older program against possibly migrated storage. Recovery requires explicit authorization and compatibility review. If backup fails before replacement, the untouched old service can be restarted safely. No global Docker cleanup is performed. diff --git a/docs/deployment.zh-CN.md b/docs/deployment.zh-CN.md index dc21ae5..e607e20 100644 --- a/docs/deployment.zh-CN.md +++ b/docs/deployment.zh-CN.md @@ -163,20 +163,21 @@ Bearer 认证升级需要前后端一起发布。旧 Cookie 页面不能继续 ## 开发与生产托管 -仓库 `deploy/compose.image.yml` 是仅拉镜像的模板。开发实例放在 `/docker/gitea/dev/RawMark`，生产实例放在 `/docker/main/rawmark`；将模板复制至对应实例目录并命名为 `compose.yml`，旁边放权限 600 的私有 `.env`。容器名跟随 `RAWMARK_PROJECT`，开发容器为 `rawmark-dev`。实例不依赖源码工作目录，必须明确填写： +仓库 `deploy/compose.image.yml` 是仅拉镜像的模板。开发实例放在 `/docker/gitea/dev/RawMark`，生产实例放在 `/docker/main/rawmark`；将模板复制至对应实例目录并命名为 `compose.yml`，旁边放权限 600 的私有 `.env`。项目名与容器名分别指定。实例不依赖源码工作目录，必须明确填写： ```dotenv RAWMARK_CHANNEL=development RAWMARK_PROJECT=rawmark-dev +RAWMARK_CONTAINER_NAME=RawMark-dev RAWMARK_BIND=127.0.0.1 RAWMARK_PORT=21001 RAWMARK_DATA_DIR=/docker/gitea/dev/RawMark/data -RAWMARK_IMAGE=git.134333.xyz/eezd/rawmark@sha256:<已验证摘要> +RAWMARK_IMAGE=git.134333.xyz/eezd/dev/rawmark@sha256:<已验证摘要> ``` -生产使用 channel `production`、project `rawmark`、端口 21000、`/docker/main/rawmark/data` 和 `ghcr.io/eezd/rawmark@sha256:<已验证摘要>`；迁移时保留当前监听地址。仅为新的开发目录设置 `65532:65532` 所有者，不递归修改现有生产权限，不将仓库示例模板作为运行数据挂载。 +生产使用 channel `production`、project `rawmark`、现有容器名、端口 21000、`/docker/main/rawmark/data` 和 `ghcr.io/eezd/rawmark@sha256:<已验证摘要>`；迁移时保留当前监听地址。仅为新的开发目录设置 `65532:65532` 所有者，不递归修改现有生产权限，不将仓库示例模板作为运行数据挂载。 -main push CI 自动更新开发。Gitea **Deploy production manually** 工作流只接受两端均正式发布、构建/发布回执相同且标签一致的版本。它固定 GHCR 摘要，检查原挂载与并发写入实例，仅停止本项目旧服务，备份完整数据目录和配置后替换。备份为私有文件并包含 SQLite WAL；旧镜像和备份继续保留。 +dev push CI 通过检查和隔离冒烟后自动更新开发；main push 与 PR 仅验证。本次 CI 迁移期间，正式发布及 Gitea **Deploy production manually** 工作流保持禁用，启用或执行须另行规划并授权。已准备的生产工作流要求两端正式发布及回执一致，固定 GHCR 摘要，并在替换前备份数据和配置。备份为私有文件并包含 SQLite WAL；旧镜像和备份继续保留。 替换前记录 `deployment.pending.json`，健康和前端检查通过后记录 `deployment.json`。候选版本访问数据后失败则停止候选，保留备份和 pending 记录，不自动恢复私人数据，也不直接用旧程序打开可能迁移后的数据；恢复须明确授权并核对兼容性。备份在替换前失败时，旧数据未被新程序访问，可安全重新启动旧容器。不做全局 Docker 清理。