skillhub/docs/09-deployment.md

skillhub 部署架构与运维

1 运行模型

当前仓库只保留两种运行方式：

• 开发环境：make dev-all
  • 前端和后端运行在宿主机
  • docker-compose.yml 只负责 PostgreSQL、Redis、MinIO
• 单机交付环境：docker compose --env-file .env.release -f compose.release.yml up -d
  • 前端和后端都运行在容器内
• 使用 GitHub Actions 发布到 GHCR 的镜像
• 默认发布 linux/amd64 与 linux/arm64 多架构镜像
  • PostgreSQL、Redis 与应用容器一起通过 Compose 启动

不再维护本地构建整套 demo 容器的中间模式，也不再保留 docker-compose.prod.yml。

2 单机交付拓扑

┌──────────────┐
│ Browser / CLI│
└──────┬───────┘
       │
       ▼
┌──────────────┐
│   Web/Nginx  │  published image
└──────┬───────┘
       │ /api/*
       ▼
┌──────────────┐
│ Spring Boot  │  published image
└───┬────┬─────┘
    │    │
    ▼    ▼
 PostgreSQL  Redis

说明：

• Web 容器提供静态资源，并将 /api/*、/oauth2/*、/.well-known/* 反代到后端
• 后端运行 local,docker profile 组合
• 技能包文件默认落在容器卷 skillhub_storage，保证单机环境开箱即用

3 Profile 约定

Profile	用途	说明
local	本地源码开发能力	启用 mock 登录、开发种子账号、调试日志
docker	容器网络适配	将数据库和 Redis 地址切换到 Compose 内网

单机交付环境使用 SPRING_PROFILES_ACTIVE=local,docker，原因很明确：

• 这是当前唯一能保证“镜像拉起后直接可用”的 profile 组合
• 用户无需先配置 GitHub OAuth，先用 mock 身份即可浏览和联调主要流程
• 后续如果引入专用 runtime / demo profile，可以替换这层组合，但当前方案不再新增第三条部署路径

默认可用账号：

• local-user
• local-admin

鉴权方式：

• 向后端请求携带 X-Mock-User-Id: local-user
• 或 X-Mock-User-Id: local-admin

4 开发环境

开发入口保持不变：

make dev-all

行为：

• docker-compose.yml 启动 PostgreSQL、Redis、MinIO
• server 在宿主机通过 Maven Wrapper 启动
• web 在宿主机通过 Vite 启动

常用命令：

make dev
make dev-all
make dev-down
make dev-all-down
make dev-all-reset

5 单机交付环境

5.1 启动

cp .env.release.example .env.release
docker compose --env-file .env.release -f compose.release.yml up -d

默认访问地址：

• Web UI: http://localhost
• Backend API: http://localhost:8080

5.2 关键文件

• compose.release.yml
  • 使用发布镜像，不在用户机器上执行本地构建
  • 负责拉起 PostgreSQL、Redis、server、web
  • 使用独立 Compose project name，避免与开发环境容器互相污染
• .env.release.example
  • 运行时变量模板
  • 包含镜像名、镜像版本、端口和数据库凭证

5.3 镜像标签约定

• edge
  • main 分支最新构建
  • 用于内部持续验证
• vX.Y.Z
  • 对应 Git tag
  • 用于稳定版本交付
• latest
  • 仅在语义化版本 tag 发布时更新

推荐：

• 团队内部试用：SKILLHUB_VERSION=edge
• 对外演示或文档引用：固定为某个 vX.Y.Z

6 GitHub Actions 发布流程

发布工作流文件：.github/workflows/publish-images.yml

触发条件：

• push 到 main
• push 语义化版本 tag，例如 v1.2.0
• 手动 workflow_dispatch

流程：

1. 检出代码
2. 登录 GHCR
3. 分别构建 server/Dockerfile 与 web/Dockerfile
4. 推送镜像：
   • ghcr.io/iflytek/skillhub-server
   • ghcr.io/iflytek/skillhub-web
5. 写入 edge / vX.Y.Z / latest / sha-* 标签
6. 同时发布 linux/amd64 与 linux/arm64 manifest，避免 Apple Silicon / ARM 主机依赖模拟层

7 配置管理

开发环境：

• 本地命令与 docker-compose.yml
• 非敏感默认值可直接落库或写入本地配置

单机交付环境：

• 使用 .env.release 管理 Compose 变量
• 如果 GHCR 包保持私有，用户需要先 docker login ghcr.io
• 如果要开放真实登录，再补充 OAUTH2_GITHUB_CLIENT_ID / OAUTH2_GITHUB_CLIENT_SECRET

8 可观测性

维度	方案
健康检查	web/nginx-health、server/actuator/health
日志	容器 stdout / stderr
指标	Spring Boot Actuator，后续可接 Prometheus

9 数据迁移

Flyway 仍是唯一 schema 变更入口：

• 路径：server/skillhub-app/src/main/resources/db/migration/
• 命名：V{version}__{description}.sql
• 启动策略：应用容器启动时自动执行迁移