# Aurask Technical Operations Plan

> 更新日期：2026-04-19  
> 本文档已按当前代码实现、目录结构、门户登录流与 DevCloud 默认部署方式同步更新。

## 1. 当前阶段定位

Aurask 当前处于 **可运行 MVP / 初版门户** 阶段，已覆盖：

- Python 模块化后端
- 标准库 HTTP Gateway
- 租户、用户、API Key、Session
- `LY SSO` / Google 登录入口
- 首次登录自动创建独立 workspace
- 配额 / TBU / 订单 / 支付闭环
- 工作流模板编排
- AnythingLLM workspace / 文档接入门面
- Langflow / AnythingLLM iframe 门户嵌入
- DevCloud 镜像与 `aurask.xyz` 默认路由对齐

当前版本适合：

- 本地演示
- 接口联调
- 首版门户交互验证
- DevCloud 环境持续迭代

当前版本尚未完成：

- PostgreSQL 正式 Repository 替换
- Redis Worker / 队列消费者
- Langflow / AnythingLLM 真正生产代理鉴权
- 完整 Ingress / NetworkPolicy / TLS / Observability

## 2. 当前目录结构

```text
api/
  README.md
  aurask/
    api.py
    app.py
    auth.py
    billing.py
    bridges/
    knowledge_base.py
    orchestrator.py
    payments.py
    plans.py
    quota.py
    repository.py
    site_config.py
protal/
  index.html
  main.js
  styles.css
manager/
  index.html
  main.js
  styles.css
deploy/
  k3s/
    README.md
    base/
tests/
  test_auth_sessions.py
  test_bridges.py
  test_mvp.py
```

说明：

- `protal/` 目录拼写继续保持既定要求
- `api/` 负责后端、桥接与门户配置
- `deploy/k3s/base/` 现已开始保存基础部署清单

## 3. 当前技术架构

### 3.1 用户访问路径

```text
Browser
  -> aurask.xyz/signin
  -> Aurask Web Protal
  -> Aurask API Gateway
  -> Session / Quota / Workflow / Knowledge services
  -> Langflow / AnythingLLM / PostgreSQL / Redis
```

### 3.2 门户结构

未登录：

- 渲染 `/signin`
- 提供 `Use LY SSO`
- 提供 `Continue with Google`

已登录：

- `Workflows` 页签：内嵌 Langflow
- `Knowledge Base` 页签：内嵌 AnythingLLM
- 右上角个人中心：展示用户、租户、workspace、套餐与退出登录

## 4. 登录与身份模型

### 4.1 登录方式

当前支持：

1. `LY SSO`
   - 以按钮形式进入
   - 当前实现为配置驱动的本地接入层
   - 通过 `AURASK_LY_SSO_USERNAME` / `AURASK_LY_SSO_PASSWORD` 控制
2. Google
   - 通过 `AURASK_GOOGLE_CLIENT_ID` 开启
   - 首次注册后自动开通独立 tenant + user + workspace

### 4.2 Token 模型

当前保留两类 Bearer Token：

- `API Key`
  - 面向接口调用
- `Session Token`
  - 面向门户登录态

### 4.3 首次登录自动开通

对新用户执行：

1. 创建 tenant
2. 创建 owner user
3. 关联外部身份
4. 开通 `free_trial`
5. 创建默认 `Personal Workspace`
6. 签发 session token

## 5. 核心模块现状

### `auth.py`

当前负责：

- tenant / user 创建
- API Key 认证
- external identity 绑定
- session 创建、校验、吊销

### `site_config.py`

当前负责：

- 公网域名
- API 地址
- Langflow / AnythingLLM 嵌入地址
- `LY SSO` / Google 开关
- DevCloud 镜像 / NodePort 默认值

### `knowledge_base.py`

当前负责：

- workspace 创建
- 文档元数据接入
- tenant 维度隔离

### `orchestrator.py`

当前负责：

- 审核模板执行
- TBU 预扣 / 结算
- workspace 绑定校验

## 6. 当前接口规划

### 6.1 公开接口

```text
GET  /health
GET  /plans
GET  /auth/config
POST /auth/ly-sso/login
POST /auth/google/login
POST /demo/bootstrap
POST /tenants
```

### 6.2 登录后接口

```text
GET  /auth/session
POST /auth/logout
GET  /me
GET  /quota
GET  /workflow-templates
GET  /workspaces
POST /workspaces
POST /documents
POST /orders
POST /payments/match
POST /workflow-runs
GET  /workflow-runs/{run_id}
GET  /admin/bridge-status
```

## 7. DevCloud 对齐结果

根据 `devcloud` 当前仓库，Aurask 已知线上默认值如下：

- API 镜像：`registry.mydevcloud.love/devcloud/aurask-api:latest`
- Web 镜像：`registry.mydevcloud.love/devcloud/aurask-web:latest`
- API NodePort：`30091`
- Web NodePort：`30090`
- 线上 API 入口：`https://aurask.xyz/api`
- 线上 Web 入口：`https://aurask.xyz`

这些值已经体现在：

- `api/aurask/site_config.py`
- `deploy/k3s/base/aurask-config.yaml`
- `deploy/k3s/base/aurask-api.yaml`
- `deploy/k3s/base/aurask-web.yaml`

## 8. k3s 首版部署路径

### 8.1 当前已落地清单

```text
deploy/k3s/base/namespace.yaml
deploy/k3s/base/aurask-config.yaml
deploy/k3s/base/secrets.example.yaml
deploy/k3s/base/aurask-api.yaml
deploy/k3s/base/aurask-web.yaml
deploy/k3s/base/kustomization.yaml
```

### 8.2 首版目标

按 `300 MAU` 规划：

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

基础服务：

- `aurask-api`
- `aurask-web`
- PostgreSQL + PGVector
- Redis
- Langflow
- AnythingLLM

## 9. 运行时与嵌入要求

### 9.1 Langflow

当前门户要求：

- 在登录后以 iframe 嵌入
- 地址由 `AURASK_PUBLIC_LANGFLOW_URL` 控制

后续生产建议：

- 使用 Aurask 网关代理转发
- 加入 session 校验
- 只暴露审核过的模板能力

### 9.2 AnythingLLM

当前门户要求：

- 在登录后以 iframe 嵌入
- 地址由 `AURASK_PUBLIC_ANYTHINGLLM_URL` 控制

后续生产建议：

- 由 Aurask 代理 workspace 身份
- 不对终端用户暴露全局管理后台

## 10. 安全与隔离原则

当前仍坚持以下边界：

- 所有核心实体保留 `tenant_id`
- workspace 必须绑定 tenant
- workflow 执行前必须预扣 TBU
- 文档接入路径保留 `tenant_id/workspace_id/document_id`
- 密码、API Key、OAuth client 不写入 Git

针对当前 iframe 方案，后续必须补强：

- Langflow / AnythingLLM 代理鉴权
- session 到 runtime 的信任链
- CSP / X-Frame-Options / SameSite 策略

## 11. 验证状态

当前已通过：

```text
python -m unittest discover -s tests -v
```

已覆盖：

- MVP 核心业务闭环
- 桥接配置契约
- `LY SSO` 登录
- Google 首次登录建 workspace
- Session 认证

## 12. 下一阶段实施顺序

建议按以下顺序继续推进：

1. 用 PostgreSQL Repository 替换 `JsonStore`
2. 引入 Redis 队列与 `aurask-worker`
3. 为 Langflow / AnythingLLM 增加网关代理层
4. 补齐 `deploy/k3s/base` 的 runtime / data / ingress / secrets 清单
5. 增加观测与告警
6. 增加支付风控与异常订单后台

## 13. 参考文件

- `README.md`
- `api/README.md`
- `protal/README.md`
- `deploy/k3s/README.md`
- `tests/test_auth_sessions.py`