mirror of
https://github.com/iflytek/skillhub.git
synced 2026-09-14 23:21:08 +00:00
179 lines
4.8 KiB
Markdown
179 lines
4.8 KiB
Markdown
# 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 开发环境
|
||
|
||
开发入口保持不变：
|
||
|
||
```bash
|
||
make dev-all
|
||
```
|
||
|
||
行为：
|
||
|
||
- `docker-compose.yml` 启动 PostgreSQL、Redis、MinIO
|
||
- `server` 在宿主机通过 Maven Wrapper 启动
|
||
- `web` 在宿主机通过 Vite 启动
|
||
|
||
常用命令：
|
||
|
||
```bash
|
||
make dev
|
||
make dev-all
|
||
make dev-down
|
||
make dev-all-down
|
||
make dev-all-reset
|
||
```
|
||
|
||
## 5 单机交付环境
|
||
|
||
### 5.1 启动
|
||
|
||
```bash
|
||
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`
|
||
- 启动策略：应用容器启动时自动执行迁移
|