Skip to content

Commit c0f7900

Browse files
XiaoSeSXiaoSeS
authored
docs: add Kubernetes deployment guide with overlays structure (iflytek#219)
* docs: simplify runtime script usage Unify to use runtime.sh for all deployment commands, removing the distinction between "official images" and "Aliyun mirror". The --aliyun parameter is preserved for users in China to specify the mirror. Changes: - Remove runtime-github.sh references, use runtime.sh uniformly - Default command uses GHCR images - Add --aliyun parameter for China users - Update README.md, README_zh.md, and docs/skillhub/ quickstart files * docs: consolidate documentation links with clear descriptions Merge the two documentation links into a single "Documentation" section with clear descriptions of each: - User Guide: skill publishing, search, CLI usage - Developer Docs: architecture, API reference, deployment This makes it easier for users to find the right documentation. * docs: consolidate documentation links with clear descriptions Merge the two documentation links into a single "Documentation" section with clear descriptions of each: - User Guide: skill publishing, search, CLI usage - Developer Docs: architecture, API reference, deployment This makes it easier for users to find the right documentation. * fix: include --home parameter in shutdown command When starting with a custom --home directory, the generated shutdown command now includes the same --home parameter to ensure it can find the correct compose files. * docs: add Kubernetes deployment guide with overlays structure - Restructure k8s configs with base/overlays pattern for flexibility - Add overlays/with-infra for full deployment (PostgreSQL + Redis) - Add overlays/external for external database scenarios - Add comprehensive ConfigMap with bootstrap admin settings - Fix health check path to /actuator/health (auth issue) - Add SKILLHUB_API_UPSTREAM env for frontend - Set SESSION_COOKIE_SECURE=false for HTTP environments - Add Chinese and English documentation in docs/skillhub/ * docs: update k8s README with complete config reference
1 parent 37c25c3 commit c0f7900

18 files changed

Lines changed: 1245 additions & 38 deletions

‎deploy/k8s/README.md‎

Lines changed: 310 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,310 @@
1+
# Kubernetes 部署指南
2+
3+
本文档说明如何在 Kubernetes 集群中部署 SkillHub。
4+
5+
## 前置条件
6+
7+
- Kubernetes 集群 (v1.24+)
8+
- kubectl 已配置并连接到集群
9+
- nginx ingress controller 已安装（可选，用于域名访问）
10+
- 默认 StorageClass 已配置（用于 PVC）
11+
12+
## 目录结构
13+
14+
```
15+
deploy/k8s/
16+
├── base/ # 基础配置（所有场景共用）
17+
│ ├── kustomization.yaml
18+
│ ├── configmap.yaml
19+
│ ├── secret.yaml.example
20+
│ ├── services.yaml
21+
│ ├── backend-deployment.yaml
22+
│ ├── frontend-deployment.yaml
23+
│ ├── scanner-deployment.yaml
24+
│ └── ingress.yaml
25+
│
26+
└── overlays/
27+
├── with-infra/ # 完整部署（包含内置数据库）
28+
│ ├── kustomization.yaml
29+
│ ├── postgres-statefulset.yaml
30+
│ └── redis-statefulset.yaml
31+
│
32+
└── external/ # 外部数据库
33+
└── kustomization.yaml
34+
```
35+
36+
## 快速开始
37+
38+
### 1. 创建命名空间
39+
40+
```bash
41+
kubectl create namespace skillhub
42+
```
43+
44+
### 2. 配置 Secret
45+
46+
```bash
47+
cd deploy/k8s/base
48+
49+
# 复制示例文件
50+
cp secret.yaml.example secret.yaml
51+
52+
# 编辑 secret.yaml，修改敏感配置
53+
```
54+
55+
**Secret 配置项**：
56+
57+
| 键 | 说明 | 必填 |
58+
|---|---|---|
59+
| spring-datasource-url | PostgreSQL 连接 URL | 是 |
60+
| spring-datasource-username | 数据库用户名 | 是 |
61+
| spring-datasource-password | 数据库密码 | 是 |
62+
| bootstrap-admin-password | 管理员密码 | 是 |
63+
| oauth2-github-client-id | GitHub OAuth ID | 否 |
64+
| oauth2-github-client-secret | GitHub OAuth 密钥 | 否 |
65+
| skill-scanner-llm-api-key | LLM API 密钥 | 否 |
66+
67+
### 3. 选择部署方式
68+
69+
**方式一：完整部署（包含 PostgreSQL + Redis）**
70+
71+
适合全新环境，自动部署数据库：
72+
73+
```bash
74+
kubectl apply -k overlays/with-infra/
75+
```
76+
77+
**方式二：使用外部数据库**
78+
79+
适合已有 PostgreSQL 和 Redis 的环境：
80+
81+
1. 修改 `base/configmap.yaml` 中的 Redis 配置：
82+
```yaml
83+
redis-host: your-redis-host
84+
redis-port: "6379"
85+
```
86+
87+
2. 修改 `base/secret.yaml` 中的数据库连接：
88+
```yaml
89+
spring-datasource-url: jdbc:postgresql://your-postgres-host:5432/skillhub
90+
```
91+
92+
3. 部署：
93+
```bash
94+
kubectl apply -k overlays/external/
95+
```
96+
97+
### 4. 验证部署
98+
99+
```bash
100+
# 检查 Pod 状态
101+
kubectl get pods -n skillhub
102+
103+
# 等待所有 Pod 就绪
104+
kubectl wait --for=condition=ready pod --all -n skillhub --timeout=300s
105+
```
106+
107+
### 5. 访问服务
108+
109+
**方式一：端口转发（推荐本地测试）**
110+
111+
```bash
112+
# 前端
113+
kubectl port-forward svc/skillhub-web -n skillhub 8080:80
114+
115+
# 后端 API
116+
kubectl port-forward svc/skillhub-server -n skillhub 8081:8080
117+
```
118+
119+
访问 http://localhost:8080
120+
121+
**方式二：Ingress 域名访问**
122+
123+
修改 `base/ingress.yaml` 中的域名：
124+
```yaml
125+
spec:
126+
rules:
127+
- host: your-domain.com # 修改为你的域名
128+
```
129+
130+
```bash
131+
kubectl apply -k overlays/with-infra/ # 或 overlays/external/
132+
```
133+
134+
## 部署架构
135+
136+
```
137+
┌─────────────────────────────────────────────────────────────┐
138+
│ skillhub namespace │
139+
├─────────────────────────────────────────────────────────────┤
140+
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
141+
│ │ skillhub-web│ │skillhub- │ │ skillhub-scanner │ │
142+
│ │ (前端) │ │ server │ │ (扫描器) │ │
143+
│ │ :80 │ │ (后端) │ │ :8000 │ │
144+
│ └─────────────┘ │ :8080 │ └─────────────────────┘ │
145+
│ └──────┬──────┘ │
146+
│ │ │
147+
│ ┌────────────────┴────────────────┐ │
148+
│ │ with-infra only │ │
149+
│ │ ┌─────────────┐ ┌───────────┐ │ │
150+
│ │ │ postgres-0 │ │ redis-0 │ │ │
151+
│ │ │ :5432 │ │ :6379 │ │ │
152+
│ │ └─────────────┘ └───────────┘ │ │
153+
│ └─────────────────────────────────┘ │
154+
│ │
155+
│ ┌─────────────────────────────────────────────────────────┐ │
156+
│ │ PersistentVolumeClaims │ │
157+
│ │ - skillhub-storage-pvc (10Gi) │ │
158+
│ │ - postgres-data-0 (10Gi) - with-infra only │ │
159+
│ │ - redis-data-0 (5Gi) - with-infra only │ │
160+
│ └─────────────────────────────────────────────────────────┘ │
161+
└─────────────────────────────────────────────────────────────┘
162+
```
163+
164+
## 配置说明
165+
166+
### ConfigMap 配置项
167+
168+
| 键 | 默认值 | 说明 |
169+
|---|---|---|
170+
| redis-host | redis | Redis 主机地址 |
171+
| redis-port | 6379 | Redis 端口 |
172+
| storage-base-path | /var/lib/skillhub/storage | 技能存储路径 |
173+
| skillhub-storage-provider | local | 存储类型（local/s3） |
174+
| skill-scanner-enabled | true | 是否启用扫描器 |
175+
| skill-scanner-url | http://skillhub-scanner:8000 | 扫描器地址 |
176+
| skill-scanner-mode | upload | 扫描模式 |
177+
| bootstrap-admin-enabled | true | 是否创建默认管理员 |
178+
| bootstrap-admin-user-id | docker-admin | 管理员用户 ID |
179+
| bootstrap-admin-username | admin | 管理员用户名 |
180+
| bootstrap-admin-display-name | Platform Admin | 管理员显示名称 |
181+
| bootstrap-admin-email | admin@example.com | 管理员邮箱 |
182+
| session-cookie-secure | false | HTTPS 环境设为 true |
183+
184+
### Secret 配置项
185+
186+
| 键 | 说明 | 必填 |
187+
|---|---|---|
188+
| spring-datasource-url | PostgreSQL 连接 URL | 是 |
189+
| spring-datasource-username | 数据库用户名 | 是 |
190+
| spring-datasource-password | 数据库密码 | 是 |
191+
| bootstrap-admin-password | 管理员密码 | 是 |
192+
| oauth2-github-client-id | GitHub OAuth ID | 否 |
193+
| oauth2-github-client-secret | GitHub OAuth 密钥 | 否 |
194+
| skill-scanner-llm-api-key | LLM API 密钥 | 否 |
195+
| skill-scanner-llm-model | LLM 模型名称 | 否 |
196+
197+
### 存储配置
198+
199+
**本地存储（默认）**
200+
201+
默认使用本地文件存储，数据保存在 PVC `skillhub-storage-pvc` 中。
202+
203+
**S3/OSS 存储**
204+
205+
生产环境建议使用 S3 兼容的对象存储：
206+
207+
1. 修改 ConfigMap：
208+
```yaml
209+
skillhub-storage-provider: s3
210+
```
211+
212+
2. 在 Secret 中添加：
213+
```yaml
214+
skillhub-storage-s3-access-key: your-access-key
215+
skillhub-storage-s3-secret-key: your-secret-key
216+
```
217+
218+
3. 在 backend-deployment.yaml 中添加环境变量：
219+
```yaml
220+
- name: SKILLHUB_STORAGE_S3_ENDPOINT
221+
value: https://oss-cn-shanghai.aliyuncs.com
222+
- name: SKILLHUB_STORAGE_S3_BUCKET
223+
value: skillhub-prod
224+
- name: SKILLHUB_STORAGE_S3_REGION
225+
value: cn-shanghai
226+
```
227+
228+
### 持久化存储
229+
230+
| PVC | 大小 | 说明 |
231+
|-----|------|------|
232+
| skillhub-storage-pvc | 10Gi | 技能文件存储 |
233+
| postgres-data-0 | 10Gi | PostgreSQL 数据（with-infra only） |
234+
| redis-data-0 | 5Gi | Redis 数据（with-infra only） |
235+
236+
## 镜像说明
237+
238+
| 组件 | 镜像 |
239+
|---|---|
240+
| 后端服务 | ghcr.io/iflytek/skillhub-server:latest |
241+
| 前端服务 | ghcr.io/iflytek/skillhub-web:latest |
242+
| 扫描器 | ghcr.io/iflytek/skillhub-scanner:latest |
243+
| PostgreSQL | postgres:16-alpine |
244+
| Redis | redis:7-alpine |
245+
246+
## 默认管理员
247+
248+
首次启动时，如果 `bootstrap-admin-enabled` 为 `true`，系统会自动创建管理员账户：
249+
250+
- 用户名：`admin`
251+
- 密码：在 `secret.yaml` 的 `bootstrap-admin-password` 中配置
252+
253+
**安全建议**：首次登录后，请立即修改默认密码。
254+
255+
## 常见问题
256+
257+
### Pod 一直 Pending
258+
259+
```bash
260+
# 检查 PVC 是否绑定
261+
kubectl get pvc -n skillhub
262+
263+
# 检查节点资源
264+
kubectl describe node <node-name>
265+
```
266+
267+
### 镜像拉取失败
268+
269+
如果镜像私有，需要创建拉取凭证：
270+
271+
```bash
272+
kubectl create secret docker-registry ghcr-secret \
273+
--docker-server=ghcr.io \
274+
--docker-username=<GitHub用户名> \
275+
--docker-password=<GitHub Token> \
276+
-n skillhub
277+
```
278+
279+
### 数据库连接失败
280+
281+
```bash
282+
# 检查 PostgreSQL 是否就绪
283+
kubectl logs postgres-0 -n skillhub
284+
285+
# 检查 Secret 配置
286+
kubectl get secret skillhub-secret -n skillhub -o yaml
287+
```
288+
289+
### 查看日志
290+
291+
```bash
292+
# 后端日志
293+
kubectl logs -l app.kubernetes.io/name=skillhub-server -n skillhub -f
294+
295+
# 前端日志
296+
kubectl logs -l app.kubernetes.io/name=skillhub-web -n skillhub -f
297+
298+
# 扫描器日志
299+
kubectl logs -l app.kubernetes.io/name=skillhub-scanner -n skillhub -f
300+
```
301+
302+
## 清理
303+
304+
```bash
305+
# 删除所有资源
306+
kubectl delete -k overlays/with-infra/ # 或 overlays/external/
307+
308+
# 删除命名空间
309+
kubectl delete namespace skillhub
310+
```

0 commit comments

Comments
 (0)