aurask/deploy/k3s/README.md

# Aurask `k3s` 部署方案（当前 DevCloud 部署与后续扩展）

## 当前 DevCloud 落地方案

当前 `master` 分支已经对接 DevCloud 的实际部署形态，先以 **Aurask MVP 网关 + 轻量前端入口页** 方式稳定上线，再逐步扩展为文档中规划的完整生产架构。

### 当前已落地组件

- `aurask-api`
  - 镜像：`registry.mydevcloud.love/devcloud/aurask-api`
  - 节点：`45.113.2.55`
  - Kubernetes 节点名：`devcloud-trade-agent-1`
  - Service：`NodePort 30091`
- `aurask-web`
  - 镜像：`registry.mydevcloud.love/devcloud/aurask-web`
  - 节点：`154.193.250.23`
  - Kubernetes 节点名：`devcloud-trade-agent-2`
  - Service：`NodePort 30090`
- `aurask` 命名空间
- `aurask-api-state` PVC
  - `StorageClass`: `local-path`
  - 用于保存 MVP JSON 状态文件

### 当前公网入口

- 域名：`https://aurask.xyz`
- 路由方式：
  - `/` -> `aurask-web`
  - `/api/*` -> `aurask-api`
- 边界入口通过前端节点宿主机 `Caddy` 转发：
  - `154.193.250.23:443` -> `NodePort 30090 / 30091`

### 当前未纳入首版自动部署的组件

以下内容仍属于后续扩展计划，**当前 `master` 分支自动发布不会部署**：

- PostgreSQL
- `PGVector` / 独立向量数据库
- Redis
- `aurask-worker`
- Langflow Runtime
- AnythingLLM
- Observability / Longhorn / CNPG

### 自动发布流水线

仓库内置 Gitea Actions 工作流：

- 文件：`.gitea/workflows/aurask-release.yml`
- 触发条件：`master` 分支 push
- 动作：
  - 运行单元测试
  - 构建 `aurask-api` 镜像
  - 构建 `aurask-web` 镜像
  - 推送镜像到私有仓库
  - 通过 SSH 连接 `64.90.15.15`
  - `kubectl apply -k deploy/k3s/base`
  - 自动更新 `aurask-api` 与 `aurask-web` 镜像到当前 commit SHA

### 仓库所需 Gitea Actions Secrets

- `SSH_PRIVATE_KEY`
- `REGISTRY_USER`
- `REGISTRY_PASSWORD`

### 当前仓库内的部署资产位置

```text
deploy/
  images/
    aurask-api/
      Dockerfile
    aurask-web/
      Dockerfile
      index.html
  k3s/
    base/
      namespace.yaml
      aurask-api-pvc.yaml
      aurask-api.yaml
      aurask-web.yaml
      kustomization.yaml
```

## 目标扩展方案（300 名月度活跃用户）

本部署计划基于当前仓库结构更新：

```text
api/       # 后端服务、桥接配置、前端到后端请求契约
protal/    # 用户前端使用面板
manager/   # 管理员前端使用面板
deploy/    # k3s 与后续部署配置
```

目标是支撑 **约 300 名月度活跃付费用户**，并满足 `Aurask_Technical_Operations_Plan.md` 中的核心边界：

- Aurask 网关是唯一公网业务入口。
- `Langflow`、`AnythingLLM`、`PostgreSQL`、`PGVector`、`Redis` 不直接暴露公网。
- 基础用户只运行审核模板，不开放任意代码执行。
- AnythingLLM Workspace 与 Aurask `tenant_id` 绑定。
- 工作流执行前预扣 TBU，执行后按实际消耗结算。
- 支付、额度、审计、成本链路可追踪。

## 1. 当前代码到集群工作负载映射

当前仓库虽然仍是 Python 模块化单体，但已经按生产职责拆出目录和桥接层。部署时按以下方式映射：

| 仓库目录/模块 | k3s 工作负载 | 说明 |
| --- | --- | --- |
| `api/aurask/api.py` | `aurask-api` | HTTP 网关、鉴权、订单、额度、前端请求入口 |
| `api/aurask/cli.py` | `aurask-api` / `aurask-worker` 启动入口 | 当前用同一镜像不同命令启动 |
| `api/aurask/orchestrator.py` | `aurask-worker` | 工作流编排、TBU 预扣/结算、调用 Langflow |
| `api/aurask/payments.py` | `aurask-worker` / `aurask-cron` | 支付匹配、后续链上监听 |
| `api/aurask/bridges/postgres.py` | `aurask-api` / `aurask-worker` | PostgreSQL schema contract |
| `api/aurask/bridges/pgvector.py` | `aurask-worker` | 向量检索契约，强制租户过滤 |
| `api/aurask/bridges/redis_bridge.py` | `aurask-api` / `aurask-worker` | 队列、缓存、幂等、限流 key 规则 |
| `api/aurask/bridges/anythingllm.py` | `aurask-worker` | AnythingLLM Workspace / 文档入库桥接 |
| `api/aurask/bridges/langflow.py` | `aurask-worker` | Langflow 模板运行桥接 |
| `protal/` | `aurask-protal` | 用户前端静态站点 |
| `manager/` | `aurask-manager` | 管理员前端静态站点 |
| `deploy/k3s/` | GitOps / Kustomize / Helm | 部署配置根目录 |

## 2. 容量假设

300 MAU 首版不是 300 并发。按以下容量规划：

- 月度活跃付费用户：`300`
- 日活高峰：`40-80`
- 同时在线用户峰值：`15-30`
- 同时工作流执行峰值：`10-20`
- 文档总量：`<= 500GB`
- 向量层：首版 `PostgreSQL + PGVector`
- 模型推理：外部模型 API / LLM Proxy，不在集群内自建 GPU 推理
- Runtime：基础用户共享 Runtime Pool，高付费用户后续独立 Namespace

触发扩容条件：

- 持续并发工作流 `> 20`
- 文档总量 `> 500GB`
- 高付费独立空间用户 `> 20`
- 工作流排队 P95 `> 10s`
- PostgreSQL 连接数、WAL、磁盘或 CPU 持续接近上限

## 3. 集群拓扑

推荐首版生产拓扑：

| 角色 | 数量 | 建议配置 | 用途 |
| --- | ---: | --- | --- |
| Public LB | 1 | 云负载均衡或 `HAProxy/Keepalived` | 统一暴露 `80/443` |
| `k3s` server | 3 | `4 vCPU / 8GB RAM / 120GB SSD` | 控制面 + embedded etcd |
| General worker | 2 | `8 vCPU / 16GB RAM / 200GB SSD` | `aurask-api`、前端、Ingress、观测 |
| Runtime worker | 2 | `8 vCPU / 16GB RAM / 250GB SSD` | `aurask-worker`、Langflow、AnythingLLM |
| Data worker | 可选 1-2 | `8 vCPU / 16GB RAM / 300GB+ SSD/NVMe` | PostgreSQL、Redis、存储密集型组件 |

如果预算有限，可先用 `3 server + 4 worker`，将 Data worker 合并到 worker 池；但 PostgreSQL 节点必须通过反亲和规则打散。

## 4. Namespace 规划

| Namespace | 组件 |
| --- | --- |
| `ingress-system` | Traefik / Nginx Ingress、External DNS |
| `cert-manager` | TLS 证书 |
| `aurask-api` | `aurask-api`、API Secret、API ServiceAccount |
| `aurask-web` | `aurask-protal`、`aurask-manager` 静态前端 |
| `aurask-runtime` | `aurask-worker`、`langflow-runtime`、`anythingllm` |
| `aurask-data` | PostgreSQL、PGVector、PgBouncer、Redis |
| `observability` | Prometheus、Grafana、Loki、Alertmanager |
| `longhorn-system` | Longhorn |

要求：

- 默认 `NetworkPolicy` 为 `deny-all`。
- 只允许 `aurask-api` 接收公网 Ingress 流量。
- `aurask-protal`、`aurask-manager` 可以暴露公网，但它们只访问 `aurask-api`。
- `Langflow`、`AnythingLLM`、`PostgreSQL`、`Redis` 仅 `ClusterIP`。

## 5. 应用工作负载

### 5.1 `aurask-api`

来源：

- `api/aurask/api.py`
- `api/aurask/app.py`
- `api/aurask/auth.py`
- `api/aurask/billing.py`
- `api/aurask/quota.py`

职责：

- HTTP 网关。
- 鉴权。
- 租户上下文注入。
- 套餐、订单、额度查询。
- 前端请求入口。
- 管理端桥接状态接口：`GET /admin/bridge-status`。

建议：

| 项目 | 值 |
| --- | --- |
| 副本 | `3` |
| requests | `500m CPU / 1Gi RAM` |
| limits | `1 CPU / 2Gi RAM` |
| HPA | CPU 65% 或 QPS 指标，扩到 `5` |
| PDB | `minAvailable=2` |

### 5.2 `aurask-worker`

来源：

- `api/aurask/orchestrator.py`
- `api/aurask/knowledge_base.py`
- `api/aurask/payments.py`
- `api/aurask/bridges/*`

职责：

- 工作流编排。
- TBU 预扣与结算。
- 调用 Langflow Runtime。
- 调用 AnythingLLM。
- 处理文档入库。
- 后续消费 Redis 队列。

建议：

| 项目 | 值 |
| --- | --- |
| 副本 | `3` |
| requests | `1 CPU / 2Gi RAM` |
| limits | `2 CPU / 4Gi RAM` |
| HPA/KEDA | 按 Redis 队列长度扩到 `6` |
| 调度 | 优先 Runtime worker |

### 5.3 `aurask-cron`

职责：

- 过期订单处理。
- 支付异常扫描。
- 周报/月报。
- 备份检查。
- 成本报表归集。

建议：

| 项目 | 值 |
| --- | --- |
| 类型 | `CronJob` |
| requests | `250m CPU / 512Mi RAM` |
| limits | `500m CPU / 1Gi RAM` |

### 5.4 `aurask-protal`

来源：`protal/`

职责：

- 用户登录后的使用面板。
- 调用 Aurask API。
- 创建 Workspace、运行模板、查看额度。

建议：

| 项目 | 值 |
| --- | --- |
| 类型 | 静态站点 Deployment |
| 副本 | `2` |
| requests | `50m CPU / 64Mi RAM` |
| limits | `200m CPU / 256Mi RAM` |
| Ingress host | `app.aurask.example.com` |

### 5.5 `aurask-manager`

来源：`manager/`

职责：

- 管理员使用面板。
- 查看桥接状态。
- 后续扩展租户、订单、异常支付、成本、审计。

建议：

| 项目 | 值 |
| --- | --- |
| 类型 | 静态站点 Deployment |
| 副本 | `2` |
| requests | `50m CPU / 64Mi RAM` |
| limits | `200m CPU / 256Mi RAM` |
| Ingress host | `manager.aurask.example.com` |
| 额外保护 | IP allowlist / SSO / BasicAuth / 二次认证 |

## 6. Runtime 组件

### 6.1 Langflow Runtime

部署名：`langflow-runtime`

用途：

- 仅执行 Aurask 审核过的模板工作流。
- 不向普通用户暴露 Langflow UI。
- 被 `aurask-worker` 通过内部 Service 调用。

建议：

| 项目 | 值 |
| --- | --- |
| 副本 | `3` |
| requests | `1500m CPU / 3Gi RAM` |
| limits | `3 CPU / 6Gi RAM` |
| Service | `ClusterIP` |
| 调度 | Runtime worker |

关键环境变量：

```text
LANGFLOW_AUTO_LOGIN=False
LANGFLOW_FALLBACK_TO_ENV_VAR=False
LANGFLOW_DATABASE_URL=postgresql://...
LANGFLOW_SECRET_KEY=<secret>
```

Aurask 侧桥接：

```text
AURASK_LANGFLOW_BASE_URL=http://langflow-runtime.aurask-runtime.svc.cluster.local:7860
AURASK_LANGFLOW_API_KEY=<secret>
```

### 6.2 AnythingLLM

部署名：`anythingllm`

用途：

- Workspace。
- 文档入库。
- RAG。
- 聊天历史。

建议：

| 项目 | 值 |
| --- | --- |
| 副本 | `2` |
| requests | `1 CPU / 2Gi RAM` |
| limits | `2 CPU / 4Gi RAM` |
| Service | `ClusterIP` |
| 调度 | Runtime worker |

Aurask 侧桥接：

```text
AURASK_ANYTHINGLLM_BASE_URL=http://anythingllm.aurask-runtime.svc.cluster.local:3001
AURASK_ANYTHINGLLM_API_KEY=<secret>
```

要求：

- 管理员账号仅由 Aurask 后台持有。
- 普通用户不进入 AnythingLLM 管理后台。
- Workspace 必须通过 Aurask 创建并绑定 `tenant_id`。

## 7. 数据组件

### 7.1 PostgreSQL + PGVector

推荐：`CloudNativePG + PGVector`

用途：

- 租户、用户、订单、额度、审计。
- 向量检索起步方案。

建议：

| 项目 | 值 |
| --- | --- |
| 实例数 | `3` |
| requests | `2 CPU / 4Gi RAM` |
| limits | `4 CPU / 8Gi RAM` |
| PVC | 每实例 `200GB` 起 |
| 备份 | WAL 归档到 S3 |

Aurask schema 契约来源：

- `api/aurask/bridges/postgres.py`
- `api/aurask/bridges/pgvector.py`

必须启用：

```sql
CREATE EXTENSION IF NOT EXISTS vector;
```

### 7.2 PgBouncer

用途：

- 降低 API / Worker 连接风暴。

建议：

| 项目 | 值 |
| --- | --- |
| 副本 | `2` |
| requests | `500m CPU / 512Mi RAM` |
| limits | `1 CPU / 1Gi RAM` |

### 7.3 Redis

用途：

- 工作流队列。
- 幂等键。
- 限流。
- 短期缓存。

建议：

| 项目 | 值 |
| --- | --- |
| 副本 | `2-3` |
| requests | `500m CPU / 1Gi RAM` |
| limits | `1 CPU / 2Gi RAM` |

Aurask key 契约来源：

- `api/aurask/bridges/redis_bridge.py`

## 8. 镜像构建计划

当前仓库建议构建三个镜像：

| 镜像 | 来源目录 | 用途 |
| --- | --- | --- |
| `aurask-api` | `api/` | 后端 API 与 worker 运行时 |
| `aurask-protal` | `protal/` | 用户前端静态站点 |
| `aurask-manager` | `manager/` | 管理员前端静态站点 |

首版可先使用同一个 Python 镜像启动 `aurask-api` 与 `aurask-worker`：

```text
aurask-api:     python -m aurask serve --host 0.0.0.0 --port 8080
aurask-worker:  python -m aurask worker   # 后续补真实 worker 命令
```

在真实 worker 命令完成前，`aurask-worker` 可先部署为保留工作负载或运行后台 cron/队列消费者占位。

## 9. 环境变量

`aurask-api` 与 `aurask-worker` 共享：

```text
AURASK_USE_EXTERNAL_BRIDGES=true
AURASK_DATABASE_URL=postgresql://aurask:<password>@pgbouncer.aurask-data.svc.cluster.local:5432/aurask
AURASK_POSTGRES_MIN_CONNECTIONS=1
AURASK_POSTGRES_MAX_CONNECTIONS=10
AURASK_PGVECTOR_TABLE=aurask_vectors
AURASK_PGVECTOR_DIMENSION=1536
AURASK_REDIS_URL=redis://redis.aurask-data.svc.cluster.local:6379/0
AURASK_REDIS_WORKFLOW_QUEUE=aurask:workflow-runs
AURASK_ANYTHINGLLM_BASE_URL=http://anythingllm.aurask-runtime.svc.cluster.local:3001
AURASK_ANYTHINGLLM_API_KEY=<secret>
AURASK_LANGFLOW_BASE_URL=http://langflow-runtime.aurask-runtime.svc.cluster.local:7860
AURASK_LANGFLOW_API_KEY=<secret>
```

Secret 管理：

- 推荐 `External Secrets Operator`。
- 或使用 `SOPS + age` 管理 GitOps secret。
- 禁止将真实 API Key、数据库密码、钱包配置提交到 Git。

## 10. Ingress 规划

建议域名：

| Host | Service | 说明 |
| --- | --- | --- |
| `api.aurask.example.com` | `aurask-api` | API 网关 |
| `app.aurask.example.com` | `aurask-protal` | 用户面板 |
| `manager.aurask.example.com` | `aurask-manager` | 管理员面板 |

不创建公网 Ingress：

- `langflow-runtime`
- `anythingllm`
- `postgres`
- `pgbouncer`
- `redis`

管理员面板额外要求：

- IP allowlist。
- SSO / BasicAuth / 二次认证。
- 操作审计。

## 11. NetworkPolicy 规划

默认拒绝所有东西向访问，然后按链路放通：

| From | To | Purpose |
| --- | --- | --- |
| Ingress | `aurask-api` | API 流量 |
| Ingress | `aurask-protal` | 用户面板 |
| Ingress | `aurask-manager` | 管理面板 |
| `aurask-api` | PgBouncer | 业务读写 |
| `aurask-worker` | PgBouncer | 业务读写 |
| `aurask-api` | Redis | 限流、缓存 |
| `aurask-worker` | Redis | 队列、幂等 |
| `aurask-worker` | Langflow | 模板执行 |
| `aurask-worker` | AnythingLLM | Workspace / 文档 / RAG |
| Langflow | 外部 LLM Proxy | 模型调用 |
| AnythingLLM | 外部 LLM Proxy / Object Storage | RAG 与文档处理 |

禁止：

- 用户请求直接访问 Langflow / AnythingLLM。
- 前端直接访问 PostgreSQL / Redis。
- Runtime 访问内网管理网段、云元数据地址。

## 12. 存储与备份

### 12.1 PVC

| 组件 | 存储 |
| --- | --- |
| PostgreSQL | `cnpg-fast`，优先云块存储 / NVMe |
| Redis | `longhorn-general` 或云块存储 |
| AnythingLLM | `longhorn-critical` 或外部对象存储缓存 |
| Observability | `longhorn-general` |

### 12.2 对象存储

优先外部 S3 兼容存储，用于：

- 用户文档对象。
- PostgreSQL 备份。
- Longhorn 备份。
- 审计归档。

### 12.3 备份目标

- PostgreSQL：`RPO <= 15 分钟`，`RTO <= 2 小时`。
- Longhorn：每日快照，每周备份。
- 支付订单与链上交易匹配记录：至少保留 `180` 天。
- 每月至少做一次恢复演练。

## 13. 可观测性

组件：

- Prometheus
- Grafana
- Loki
- Alertmanager
- kube-state-metrics
- node-exporter

必须监控：

- `aurask-api` QPS、P95、错误率。
- `aurask-worker` 队列深度、执行时长、失败率。
- `tbu_reserved_total`、`tbu_consumed_total`、`tbu_released_total`。
- 订单创建、支付匹配、异常订单数量。
- Langflow 执行耗时与错误率。
- AnythingLLM 文档入库耗时与失败率。
- PostgreSQL 连接数、WAL、复制延迟、磁盘。
- Redis 内存、队列长度、延迟。

## 14. 推荐部署配置目录

后续 manifests 建议落入：

```text
deploy/k3s/
  README.md
  base/
    namespaces.yaml
    ingress.yaml
    network-policies.yaml
    secrets.example.yaml
    aurask-api.yaml
    aurask-worker.yaml
    aurask-protal.yaml
    aurask-manager.yaml
    langflow-runtime.yaml
    anythingllm.yaml
    postgres-cnpg.yaml
    redis.yaml
    observability.yaml
  overlays/
    staging/
      kustomization.yaml
    production/
      kustomization.yaml
```

Helm 管理：

- `cert-manager`
- `longhorn`
- `cloudnative-pg`
- `prometheus-stack`
- `loki`
- `redis` operator 或 chart

Kustomize 管理：

- Aurask 自研服务。
- Ingress。
- NetworkPolicy。
- 环境差异。

## 15. 上线步骤

### Phase 1：集群底座

1. 创建 `3 server + 4 worker` k3s 集群。
2. 配置公网 LB 与 DNS。
3. 安装 `cert-manager`。
4. 安装 `Longhorn` 或云 CSI。
5. 安装 observability 基础栈。

### Phase 2：数据层

1. 安装 `CloudNativePG`。
2. 初始化 PostgreSQL 与 PGVector。
3. 部署 PgBouncer。
4. 部署 Redis。
5. 配置对象存储与备份桶。

### Phase 3：Aurask 应用层

1. 构建并推送 `aurask-api` 镜像。
2. 构建并推送 `aurask-protal` 镜像。
3. 构建并推送 `aurask-manager` 镜像。
4. 部署 `aurask-api`。
5. 部署 `aurask-worker`。
6. 部署 `aurask-protal` 与 `aurask-manager`。
7. 配置 Ingress、TLS、NetworkPolicy。

### Phase 4：Runtime 层

1. 部署 Langflow Runtime。
2. 部署 AnythingLLM。
3. 配置 `AURASK_LANGFLOW_*` 与 `AURASK_ANYTHINGLLM_*` secret。
4. 使用 `GET /admin/bridge-status` 验证桥接配置。
5. 跑通模板工作流与文档入库。

### Phase 5：生产化验收

1. 开启 HPA / KEDA。
2. 跑并发工作流压测。
3. 演练支付匹配。
4. 演练 PostgreSQL 备份恢复。
5. 演练节点故障与 Pod 重调度。
6. 检查 Langflow / AnythingLLM 未暴露公网。

## 16. 验收标准

| 项目 | 目标 |
| --- | --- |
| API P95 | `< 500ms`，不含外部模型调用 |
| 峰值并发工作流 | `10-20` |
| 工作流成功率 | `95%+` |
| 支付匹配成功率 | `99%+` |
| 工作流排队 P95 | `< 10s` |
| PostgreSQL RPO | `<= 15 分钟` |
| PostgreSQL RTO | `<= 2 小时` |
| 月可用性 | `99%+` |
| 外部暴露面 | 仅 API、用户面板、管理面板 |

## 17. 当前代码差距

当前已经具备：

- 根目录划分：`api`、`protal`、`manager`、`deploy`。
- PostgreSQL / PGVector / Redis / AnythingLLM / Langflow 桥接契约。
- `/admin/bridge-status` 桥接状态接口。
- 静态用户面板和管理面板。
- 请求样例：`api/requests/aurask-api.http`。

仍需补齐：

- `deploy/k3s/base` manifests。
- 真实 PostgreSQL repository。
- Redis 队列消费者。
- `aurask-worker` 独立启动命令。
- 真实 Langflow / AnythingLLM API 适配细节校验。
- 前端构建流程与容器镜像。
- Secret / NetworkPolicy / HPA / KEDA manifests。

## 18. 官方参考

- k3s HA embedded etcd：<https://docs.k3s.io/datastore/ha-embedded>
- cert-manager Installation：<https://cert-manager.io/docs/installation/>
- Longhorn Installation：<https://longhorn.io/docs/latest/deploy/install/>
- CloudNativePG Documentation：<https://cloudnative-pg.io/documentation/current/>
- CloudNativePG Backup：<https://cloudnative-pg.io/documentation/current/backup/>
- AnythingLLM System Requirements：<https://docs.anythingllm.com/installation-docker/system-requirements>
- Langflow Security：<https://docs.langflow.org/security>