# Aurask k3s / DevCloud 部署说明

本文档基于当前仓库与 DevCloud 现网结构，兼顾两部分目标：

- 保留已落地的 DevCloud `base + production overlay` 部署方式
- 纳入本次新增的门户登录流、Google 登录、Langflow / AnythingLLM 嵌入配置

## 目录结构

```text
deploy/k3s/
  README.md
  base/
    namespace.yaml
    aurask-runtime-config.yaml
    aurask-config.yaml
    aurask-api-pvc.yaml
    aurask-api.yaml
    aurask-worker.yaml
    aurask-web.yaml
    aurask-manager.yaml
    postgres.yaml
    redis.yaml
    kustomization.yaml
    secrets.example.yaml
  overlays/
    production/
      kustomization.yaml
      aurask-api-production.yaml
      aurask-worker-production.yaml
      aurask-web-production.yaml
      aurask-manager-production.yaml
      postgres-production.yaml
      redis-production.yaml
      runtime-config-production.yaml
  examples/
    aurask-runtime-secrets.example.yaml
    aurask-postgres-secret.example.yaml
    aurask-redis-secret.example.yaml
```

## 当前 DevCloud 现网映射

### 域名与入口

- 公网域名：`https://aurask.xyz`
- `https://aurask.xyz/api/*` → `aurask-api`
- `https://aurask.xyz/*` → `aurask-web`
- 当前由前端宿主机 Caddy 转发到 DevCloud NodePort

### 已知镜像与端口

- API 镜像：`registry.mydevcloud.love/devcloud/aurask-api:latest`
- Web 镜像：`registry.mydevcloud.love/devcloud/aurask-web:latest`
- Manager 镜像：`registry.mydevcloud.love/devcloud/aurask-manager:latest`
- `aurask-api` NodePort：`30091`
- `aurask-web` NodePort：`30090`
- `aurask-manager` NodePort：`30092`

### 生产 overlay 节点绑定

- `aurask-api`：`devcloud-trade-agent-1`
- `aurask-worker`：`devcloud-trade-agent-1`
- `postgres`：`devcloud-trade-agent-1`
- `redis`：`devcloud-trade-agent-1`
- `aurask-web`：`devcloud-trade-agent-2`
- `aurask-manager`：`devcloud-trade-agent-2`

## Base 层职责

`deploy/k3s/base/` 保持通用资源，不直接写死生产节点：

- `namespace.yaml`：Aurask namespace
- `aurask-runtime-config.yaml`：桥接/运行时基础配置
- `aurask-config.yaml`：站点、门户、登录、嵌入默认配置
- `aurask-api-pvc.yaml`：MVP 状态文件持久化
- `aurask-api.yaml`：API Deployment + Service
- `aurask-worker.yaml`：Worker Deployment
- `aurask-web.yaml`：用户门户 Deployment + Service
- `aurask-manager.yaml`：管理员门户 Deployment + Service
- `postgres.yaml`：PostgreSQL / PGVector 基础资源
- `redis.yaml`：Redis 基础资源

## 本次新增的门户配置

### `aurask-config.yaml`

新增以下站点默认值：

- `AURASK_PUBLIC_BASE_URL=https://aurask.xyz`
- `AURASK_PUBLIC_API_BASE_URL=https://aurask.xyz/api`
- `AURASK_PUBLIC_LANGFLOW_URL=https://aurask.xyz/runtime/langflow/`
- `AURASK_PUBLIC_ANYTHINGLLM_URL=https://aurask.xyz/runtime/anythingllm/`
- `AURASK_DEVCLOUD_API_IMAGE=registry.mydevcloud.love/devcloud/aurask-api:latest`
- `AURASK_DEVCLOUD_WEB_IMAGE=registry.mydevcloud.love/devcloud/aurask-web:latest`
- `AURASK_DEVCLOUD_API_NODE_URL=http://45.113.2.55:30091`
- `AURASK_DEVCLOUD_WEB_NODE_URL=http://45.113.2.55:30090`
- `AURASK_GOOGLE_ENABLED=true`
- `AURASK_SESSION_TTL_DAYS=7`

### `secrets.example.yaml`

新增门户与外部组件需要的 Secret 占位：

- `AURASK_DATABASE_URL`
- `AURASK_ANYTHINGLLM_API_KEY`
- `AURASK_LANGFLOW_API_KEY`
- `AURASK_GOOGLE_CLIENT_ID`

说明：

- `secrets.example.yaml` 仅作模板，不应直接提交真实密钥
- 生产建议继续使用 `External Secrets Operator` 或 `SOPS + age`

## API / Web 部署说明

### `aurask-api`

职责：

- API Gateway
- Google 登录
- Session 签发与校验
- 配额、订单、支付、工作流入口
- 返回门户配置与嵌入 URL

配置说明：

- 继续挂载 `/data/state.json`，兼容当前 MVP `JsonStore`
- 同时读取：
  - `aurask-runtime-config`
  - `aurask-config`
  - `aurask-runtime-secrets`
  - `aurask-secrets`

### `aurask-web`

职责：

- 承载 `protal/`
- 对外提供 `/signin`
- 登录后提供 `Workflows` / `Knowledge Base` 双标签工作台

## 生产 overlay 说明

`deploy/k3s/overlays/production/` 负责绑定现网特定配置：

- NodeSelector
- NodePort
- 生产 runtime 开关

当前生产 overlay 已保留：

- `aurask-api-production.yaml`
- `aurask-worker-production.yaml`
- `aurask-web-production.yaml`
- `aurask-manager-production.yaml`
- `postgres-production.yaml`
- `redis-production.yaml`
- `runtime-config-production.yaml`

## 运行时嵌入建议

当前门户已经引用：

- `https://aurask.xyz/runtime/langflow/`
- `https://aurask.xyz/runtime/anythingllm/`

建议后续分两步完成：

1. 先由公网反代到内部运行时入口
2. 再收敛为 `aurask-api` 网关代理鉴权，避免直接暴露运行时

## 300 MAU 首版建议

### 集群规模

- `3` 台 k3s server
- `2` 台 general worker
- `2` 台 runtime worker

### 组件建议

- `aurask-api`
- `aurask-web`
- `aurask-worker`
- `aurask-manager`
- PostgreSQL + PGVector
- Redis
- 后续补充 Langflow / AnythingLLM 专用清单

## 部署方式

### 应用基础资源

```powershell
kubectl apply -k deploy/k3s/base
```

### 应用生产 overlay

```powershell
kubectl apply -k deploy/k3s/overlays/production
```

## 后续建议

建议继续推进：

1. 用 PostgreSQL Repository 替换 `JsonStore`
2. 让 `aurask-worker` 接入真实 Redis 队列消费
3. 为 Langflow / AnythingLLM 增加独立清单
4. 增加 Ingress / TLS / NetworkPolicy
5. 让运行时访问统一收敛到 Aurask 网关代理