From 91b393a00c0da01c6c79483918ff9f7107e238f2 Mon Sep 17 00:00:00 2001 From: tim Date: Wed, 11 Feb 2026 19:58:59 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E5=A2=9E=E5=8A=A0=E9=83=A8=E7=BD=B2?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E4=B8=8E=E5=AF=BC=E8=88=AA=E5=85=A5=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/README.md | 1 + docs/content/docs/deployment/index.mdx | 147 +++++++++++++++++++++++++ docs/content/docs/deployment/meta.json | 3 + docs/content/docs/index.mdx | 1 + docs/content/docs/meta.json | 2 +- 5 files changed, 153 insertions(+), 1 deletion(-) create mode 100644 docs/content/docs/deployment/index.mdx create mode 100644 docs/content/docs/deployment/meta.json diff --git a/docs/README.md b/docs/README.md index ddb160ffe..3b804e63d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,4 +19,5 @@ bun dev - `frontend/` 前端技术文档 - `backend/` 后端技术文档 +- `deployment/` 预发/生产部署文档 - `openapi/` 后端 API 文档 diff --git a/docs/content/docs/deployment/index.mdx b/docs/content/docs/deployment/index.mdx new file mode 100644 index 000000000..3a6d81f0d --- /dev/null +++ b/docs/content/docs/deployment/index.mdx @@ -0,0 +1,147 @@ +--- +title: 部署指南 +description: OpenIsle 预发与生产环境部署说明 +--- + +# 部署指南 + +本页覆盖 OpenIsle 当前仓库内已有的部署链路：`deploy/` 脚本 + GitHub Actions 工作流 + Docker Compose。 + +## 部署总览 + +| 环境 | 触发方式 | 脚本 | +| --- | --- | --- | +| 预发 (staging) | `main` 分支 push / 手动触发 | `deploy/deploy_staging.sh` | +| 生产 (prod) | 每日定时 / 手动触发 | `deploy/deploy.sh` | + +说明： + +- 两套工作流共用并发锁 `openisle-server`，避免同一台服务器并发部署冲突。 +- 两个脚本都会执行 `git checkout -B origin/` + `git reset --hard origin/`，确保服务器代码与远端分支对齐。 + +## 前置条件 + +1. 服务器已安装：`git`、`docker`、`docker compose`（插件版本）。 +2. 服务器目录与脚本保持一致： + - 生产仓库路径：`/opt/openisle/OpenIsle` + - 预发仓库路径：`/opt/openisle/OpenIsle-staging` +3. 两个仓库目录下都已创建 `.env`（基于根目录 `.env.example`）。 +4. 已配置反向代理（参考 `nginx/openisle` 与 `nginx/openisle-staging`）。 + +## 环境变量准备 + +先复制模板： + +```bash +cp .env.example .env +``` + +至少确认这些变量： + +- 安全相关：`JWT_SECRET`、`JWT_REASON_SECRET`、`JWT_RESET_SECRET`、`JWT_INVITE_SECRET` +- 存储与队列：`MYSQL_*`、`REDIS_*`、`RABBITMQ_*` +- 站点与前端：`WEBSITE_URL`、`NUXT_PUBLIC_API_BASE_URL`、`NUXT_PUBLIC_WEBSOCKET_URL`、`NUXT_PUBLIC_WEBSITE_BASE_URL` + +如果同机同时跑“生产 + 预发”，预发端口必须改开，避免冲突。根据当前 Nginx 示例，预发可使用： + +```dotenv +SERVER_PORT=8081 +FRONTEND_PORT=3001 +WEBSOCKET_PORT=8083 +OPENISLE_MCP_PORT=8086 +WEBSITE_URL=https://staging.open-isle.com +NUXT_PUBLIC_API_BASE_URL=https://staging.open-isle.com +NUXT_PUBLIC_WEBSOCKET_URL=https://staging.open-isle.com/websocket +NUXT_PUBLIC_WEBSITE_BASE_URL=https://staging.open-isle.com +``` + +## 手动部署 + +在服务器执行： + +```bash +# 生产（默认 main） +bash /opt/openisle/OpenIsle/deploy/deploy.sh + +# 预发（默认 main） +bash /opt/openisle/OpenIsle/deploy/deploy_staging.sh +``` + +部署指定分支： + +```bash +bash /opt/openisle/OpenIsle/deploy/deploy.sh feature/xxx +bash /opt/openisle/OpenIsle/deploy/deploy_staging.sh feature/xxx +``` + +脚本会自动完成： + +1. 拉取并重置代码到目标分支最新提交 +2. `docker compose config` 校验 +3. 拉取基础镜像 + 构建 `frontend_service`、`mcp` +4. 重建并启动关键服务（`mysql`、`redis`、`rabbitmq`、`websocket-service`、`springboot`、`frontend_service`、`mcp`） + +## CI/CD 触发规则 + +- 预发：`.github/workflows/deploy-staging.yml` + - `main` 分支 push 自动触发 + - 支持 `workflow_dispatch` 手动触发 +- 生产：`.github/workflows/deploy.yml` + - 每天 `UTC 19:00` 定时触发（北京时间次日 `03:00`） + - 支持 `workflow_dispatch` 手动触发 +- 文档站：`.github/workflows/deploy-docs.yml` + - 在预发部署成功后触发，发布到 `gh-pages` + +## 部署后检查 + +查看容器状态： + +```bash +docker compose -f /opt/openisle/OpenIsle/docker/docker-compose.yaml --env-file /opt/openisle/OpenIsle/.env ps +docker compose -f /opt/openisle/OpenIsle-staging/docker/docker-compose.yaml --env-file /opt/openisle/OpenIsle-staging/.env ps +``` + +查看核心服务日志： + +```bash +docker compose -f /opt/openisle/OpenIsle/docker/docker-compose.yaml --env-file /opt/openisle/OpenIsle/.env logs -f springboot websocket-service frontend_service +``` + +本机健康检查（自动读取 `.env` 端口）： + +```bash +ENV_FILE=/opt/openisle/OpenIsle/.env +SERVER_PORT=$(grep '^SERVER_PORT=' "$ENV_FILE" | cut -d= -f2) +WS_PORT=$(grep '^WEBSOCKET_PORT=' "$ENV_FILE" | cut -d= -f2) +curl -fsS "http://127.0.0.1:${SERVER_PORT}/actuator/health" +curl -fsS "http://127.0.0.1:${WS_PORT}/actuator/health" +``` + +## 回滚建议 + +由于部署脚本总是对齐远端分支最新提交，回滚建议走“可追溯分支”： + +1. 在本地创建回滚分支并推送： + + ```bash + git checkout -b rollback/2026-02-11 <稳定提交SHA> + git push origin rollback/2026-02-11 + ``` + +2. 在服务器按分支重新部署： + + ```bash + bash /opt/openisle/OpenIsle/deploy/deploy.sh rollback/2026-02-11 + ``` + +同理可用于预发： + +```bash +bash /opt/openisle/OpenIsle/deploy/deploy_staging.sh rollback/2026-02-11 +``` + +## 风险提示 + +- 脚本使用 `up -d --force-recreate --remove-orphans`，目标服务会被重建，部署窗口内可能出现短时连接中断。 +- `.env` 缺失时脚本会直接退出，不会继续部署。 +- 生产与预发共机时，务必避免端口冲突并保持 Nginx upstream 端口一致。 diff --git a/docs/content/docs/deployment/meta.json b/docs/content/docs/deployment/meta.json new file mode 100644 index 000000000..c987ae816 --- /dev/null +++ b/docs/content/docs/deployment/meta.json @@ -0,0 +1,3 @@ +{ + "root": true +} diff --git a/docs/content/docs/index.mdx b/docs/content/docs/index.mdx index 23316bf67..ab1be74e7 100644 --- a/docs/content/docs/index.mdx +++ b/docs/content/docs/index.mdx @@ -11,4 +11,5 @@ OpenIsle 是一个现代化的社区平台，提供完整的社交功能。 - [后端开发指南](/backend) - 了解后端架构和开发 - [前端开发指南](/frontend) - 了解前端技术栈和组件 +- [部署指南](/deployment) - 了解预发/生产部署流程与回滚方法 - [API 文档](/openapi) - 查看完整的 API 接口文档 diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json index 699c8a827..bfb396e5d 100644 --- a/docs/content/docs/meta.json +++ b/docs/content/docs/meta.json @@ -1,3 +1,3 @@ { - "pages": ["index", "frontend", "backend", "openapi"] + "pages": ["index", "frontend", "backend", "deployment", "openapi"] }