From c68645931c6ee4f3bcfa05f9896082843449c5ad Mon Sep 17 00:00:00 2001 From: ddcat666 <26564566+ddcat666@users.noreply.github.com> Date: Tue, 13 Oct 2026 20:55:20 +0800 Subject: [PATCH] =?UTF-8?q?docs(deploy):=20=E6=9C=8D=E5=8A=A1=E5=99=A8?= =?UTF-8?q?=E9=95=9C=E5=83=8F=E9=83=A8=E7=BD=B2=E4=B8=8E=E5=9C=A8=E7=BA=BF?= =?UTF-8?q?=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 6 ++-- README.md | 49 ++++++++++++++++++--------------- docker-compose.build.yml | 6 ++++ docs/index.md | 10 ++++++- scripts/install-server-image.sh | 6 ++++ scripts/install-server.sh | 9 ++++-- 6 files changed, 59 insertions(+), 27 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 88576265f..be7225522 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,7 +14,7 @@ | `backend/` | Go 1.25、Gin、GORM、SQLite/PostgreSQL、Redis 协调 | `backend/cmd/server/main.go` | 登录、权限、业务 API、任务队列、资源、模型中转和后台管理 | | `docs/` | Next.js、Fumadocs、MDX | `docs/content/docs/` | 面向用户和开发者的专题文档；构建配置见 `docs/source.config.ts` | -根目录的 `Dockerfile` 构建前端静态镜像；`nginx.conf` 托管 SPA 并代理后端。`docker-compose.dev.yml` 是源码热更新开发编排，`docker-compose.local.yml` 是本地构建运行，`docker-compose.deploy.yml` 是 PostgreSQL + Redis 部署编排。 +根目录的 `Dockerfile` 构建前端静态镜像；`nginx.conf` 托管 SPA 并代理后端。`docker-compose.dev.yml` 是源码热更新开发编排，根 `docker-compose.yml` 和 `docker-compose.local.yml` 是本地构建运行。服务器默认使用官方 Release 镜像、`docker-compose.deploy.yml`（PostgreSQL、Redis、独立 Agent、迁移服务）和宿主机 Host Updater，详细说明见 [Docker 部署](docs/content/docs/overview/docker.mdx)。 ## 2. 开始工作前 @@ -138,7 +138,9 @@ cd web && bun run dev - 先阅读 `.env.example` 和对应 Compose 文件。宿主机后端开发必须使用 Git 忽略的 `.local/project-workbench-debug`，通过 `CANVAS_BACKEND_DATA_DIR` 显式指定；不要把 `backend/data` 当作开发账号数据库。 - 本地缓存放 `.local/cache`；不要提交数据库、上传文件、`.env`、真实密钥、构建产物或编辑器配置。 - 宿主机开发：`backend/` 运行 `CANVAS_BACKEND_DATA_DIR=../.local/project-workbench-debug go run ./cmd/server`，`web/` 使用 Bun 和 Vite；不要用 pnpm/npm 覆盖同一套 `node_modules`，也不要提交 `pnpm-lock.yaml` 或 `package-lock.json`。Docker 热更新使用 `docker-compose.dev.yml`；本地构建运行使用 `docker-compose.local.yml`。 -- 生产 Compose 使用 `docker-compose.deploy.yml`（PostgreSQL、Redis、backend、web），源码构建可叠加 `docker-compose.build.yml`。公网只暴露 web 的 `3000`，backend `8080` 留在 Compose 网络内。 +- 用户要求“部署到服务器/云服务器/生产环境”且未指定方式时，默认采用 `scripts/install-server-image.sh` + 官方已发布 Release + `docker-compose.deploy.yml` + Host Updater；先确认该 Release 的镜像、更新器二进制和 `SHA256SUMS` 可用，按同一 Release 固定 `CANVAS_IMAGE_TAG` 和 `REPOSITORY_REF`。不要自行简化成 `web/backend` 两容器 SQLite 编排或生成替代 `compose.yml`；用户明确要求源码构建或轻量试运行时才选择对应方案，并说明在线更新边界。GHCR 拉取失败应排查网络、包可见性和认证，不静默切换为不受管源码部署。 +- 生产 Compose 使用 `docker-compose.deploy.yml`（PostgreSQL、Redis、migrate、yingce-agent、backend、web）。源码构建可叠加 `docker-compose.build.yml`，但本地镜像不由 Host Updater 管理；`scripts/install-server.sh` 不安装更新器，不能当作在线更新安装入口。公网只暴露 web 的 `CANVAS_HTTP_PORT`（默认 `3000`），backend `8080` 留在 Compose 网络内。 +- 诊断已有部署时，依据实际 Compose 文件、容器镜像、数据库驱动、数据挂载和 Host Updater 状态分别报告。源码构建不等于 local，SQLite 不证明使用了 `docker-compose.local.yml`，自定义文件名也不证明采用了任何仓库编排。已有 SQLite/自定义部署须先备份、迁移和验证，再转为受管部署；不要直接覆盖原 Compose 或数据卷。 - 默认不启动 dev server；只有用户明确要求浏览器预览或联调时才启动，并先确认端口、数据目录和现有进程。 - 健康检查只能证明入口可用，不能替代登录、SSE、任务生成和资源访问验证。 diff --git a/README.md b/README.md index ff6e3b63d..53e89fa31 100644 --- a/README.md +++ b/README.md @@ -118,6 +118,8 @@ Windows PowerShell 用户可在仓库根目录执行： ### Docker 开发与本地构建 +以下命令用于本地开发或试运行。部署服务器并使用后台在线更新，请使用下文的官方 Release 镜像部署。 + 源码热更新： ```bash @@ -131,7 +133,7 @@ LOCAL_UID=$(id -u) LOCAL_GID=$(id -g) \ docker compose -f docker-compose.local.yml up -d --build ``` -默认前端端口为 `3000`、后端端口为 `8080`；端口冲突时可通过 `CANVAS_WEB_HOST_PORT` 和 `CANVAS_BACKEND_HOST_PORT` 覆盖。 +热更新开发默认前端端口为 `3000`、后端端口为 `8080`；端口冲突时可通过 `CANVAS_WEB_HOST_PORT` 和 `CANVAS_BACKEND_HOST_PORT` 覆盖。本地构建编排只暴露 web 的 `3000`，后端留在容器网络内，不安装 Host Updater。 更多本地开发说明（包括时间线字幕转写）见[本地开发文档](docs/content/docs/backend/local-development.mdx)。 @@ -155,34 +157,37 @@ docker compose -f docker-compose.local.yml up -d --build ## 服务器部署 -### 源码构建（推荐） +### 官方 Release 镜像（推荐，支持后台在线更新） -适用于 Linux 云服务器。脚本会安装 Docker、拉取源码、生成受保护的 `.env`，并启动 PostgreSQL、Redis、后端和网页： +适用于使用 systemd 的 Linux 服务器。先从 [GitHub Releases](https://github.com/ddcat-ai/open-ai-canvas/releases) 选择包含镜像、Host Updater 二进制和 `SHA256SUMS` 的已发布版本，将下方 `vX.Y.Z` 替换为该版本： + +```bash +CANVAS_RELEASE=vX.Y.Z +curl -fsSL "https://raw.githubusercontent.com/ddcat-ai/open-ai-canvas/${CANVAS_RELEASE}/scripts/install-server-image.sh" \ + | sudo env CANVAS_IMAGE_TAG="${CANVAS_RELEASE}" REPOSITORY_REF="${CANVAS_RELEASE}" bash +``` + +脚本使用 `docker-compose.deploy.yml`，启动 PostgreSQL、Redis、独立 `yingce-agent`、backend 和 web，由一次性 `migrate` 服务迁移数据库，并安装宿主机 Host Updater。backend、web、Agent 镜像会固定为对应 GHCR digest。默认访问 `http://服务器IP:3000`，安装完成后在“系统配置 → 系统更新”检查后续版本。 + +查看状态和日志： + +```bash +cd /opt/open-ai-canvas +sudo docker compose --env-file .env -f docker-compose.deploy.yml ps +sudo docker compose --env-file .env -f docker-compose.deploy.yml logs -f --tail=200 +``` + +### 源码构建与已有部署 + +需要运行自行修改的源码时，可以使用源码安装脚本： ```bash curl -fsSL https://raw.githubusercontent.com/ddcat-ai/open-ai-canvas/main/scripts/install-server.sh | sudo bash ``` -默认访问 `http://服务器IP:3000`。更新或排查： +脚本使用 PostgreSQL、Redis、独立 Agent 和源码构建叠加层，但不安装 Host Updater；该部署不属于后台在线更新管理范围，需自行构建、备份和升级。根目录的 `docker-compose.yml`、`docker-compose.local.yml` 和自行编写的两容器 SQLite 编排用于本地试运行，不作为默认服务器部署方案。 -```bash -cd /opt/open-ai-canvas -sudo docker compose --env-file .env \ - -f docker-compose.deploy.yml -f docker-compose.build.yml ps -sudo docker compose --env-file .env \ - -f docker-compose.deploy.yml -f docker-compose.build.yml logs -f --tail=200 -``` - -### 使用 GHCR 镜像 - -不需要源码时，可使用镜像部署脚本： - -```bash -curl -fsSL https://raw.githubusercontent.com/ddcat-ai/open-ai-canvas/main/scripts/install-server-image.sh \ - | sudo env CANVAS_IMAGE_TAG=v1.5.7.1 bash -``` - -脚本会先按指定 Release 拉取镜像，再解析并写入 `CANVAS_BACKEND_IMAGE`、`CANVAS_WEB_IMAGE` 的 GHCR digest；生产 Compose 不接受缺失 digest 的默认镜像或 `latest`。更新流程、数据库迁移、备份和回退说明见[系统更新文档](docs/content/docs/backend/system-update.mdx)。 +已有 SQLite 或自定义 Compose 部署，不能只替换 Compose 文件或补装更新器就获得在线更新；应先核对原数据卷、完成备份和数据迁移。方案选择见 [Docker 部署](docs/content/docs/overview/docker.mdx)，更新约束、备份和回退见[系统更新文档](docs/content/docs/backend/system-update.mdx)。 ## 安全边界 diff --git a/docker-compose.build.yml b/docker-compose.build.yml index 98b5c1d3b..a435b4253 100644 --- a/docker-compose.build.yml +++ b/docker-compose.build.yml @@ -7,6 +7,12 @@ services: args: GOPROXY: ${GOPROXY:-https://proxy.golang.org,direct} + yingce-agent: + image: open-ai-canvas-yingce-agent:server + build: + context: . + dockerfile: yingce-agent/Dockerfile + backend: image: open-ai-canvas-backend:server build: diff --git a/docs/index.md b/docs/index.md index 17655d62c..b36803617 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,14 @@ # 影策 · AI 文档索引 -面向 AI 的短索引。详细文档维护规则见 [AGENTS.md](../AGENTS.md) 第 10 节「文档同步」。 +面向 AI 的短索引。详细文档维护规则见 [AGENTS.md](../AGENTS.md) 第 9 节「文档与交付」。 + +## 部署与更新入口 + +用户要求部署服务器时，默认使用官方 Release 镜像、`docker-compose.deploy.yml` 和 Host Updater。本地 SQLite 构建与自定义 Compose 不属于后台在线更新管理范围。 + +- [Docker 部署](content/docs/overview/docker.mdx)：默认服务器方案、Compose 选择与已有部署核对。 +- [在线更新与安全回退](content/docs/backend/system-update.mdx)：受管部署条件、安装、备份、迁移和回退。 +- [本地开发](content/docs/backend/local-development.mdx)：宿主机与热更新开发环境。 ## 设计沉淀 diff --git a/scripts/install-server-image.sh b/scripts/install-server-image.sh index 5acb61b4e..9bbc86cd8 100755 --- a/scripts/install-server-image.sh +++ b/scripts/install-server-image.sh @@ -135,6 +135,9 @@ prepare_environment() { step "生成 PostgreSQL 随机密码和部署配置" local database_password database_password="$(openssl rand -hex 32)" + CANVAS_BACKEND_IMAGE="${IMAGE_REPOSITORY}-backend:${CANVAS_IMAGE_TAG}" + CANVAS_WEB_IMAGE="${IMAGE_REPOSITORY}-web:${CANVAS_IMAGE_TAG}" + CANVAS_YINGCE_AGENT_IMAGE="${IMAGE_REPOSITORY}-yingce-agent:${CANVAS_IMAGE_TAG}" umask 077 cat >.env <