Orchidea-Gateway · 天智兰心网关

Orchidea-Gateway 是 Orchidea AI 平台的企业级 AI 网关产品，遵循天智兰心产品线规范（品牌色 #8B5E3C），提供统一的大模型接入、智能路由、成本管控与内容安全能力。

产品定位

Orchidea-Gateway 是面向中大型企业的 AI 能力中枢，解决以下核心问题：

2026-11 能力更新（v0.2.1）

• 可观测链路：改用 OTLP/HTTP protobuf exporter，endpoint http://watch-otel:4318/v1/traces，与 Watch 接收器对齐
• 审计日志：统一 orchidea_audit_logs 为 repository schema，ensure_schema 增加旧表列对账与 NOT NULL 放宽
• 部署修复：补模块级 logger 与 psutil 依赖；WORKERS=1 约束下横向扩展靠多容器

2026-10 能力更新（v0.2.0）

• 策略引擎：7 类策略（内容安全/数据隐私/数据分级/访问控制/成本预算/模型使用/地区合规/时间窗口），6 种动作（allow/deny/warn/mask/quota/route），支持优先级、模型通配、团队/用户/API Key/地区/时间窗与 Token/成本阈值
• 数据分级 L1-L4：精确级别与下限表达式（>=L3、>L2），请求级级别取 metadata.data_level 或 x-orchidea-data-level；L3/L4 强制本地模型
• 链路生效：/v1/chat/completions 与 /v1/embeddings 执行策略评估，响应头返回 x-orchidea-policy-action / x-orchidea-policy-rules，命中写审计事件
• 策略管理：/v1/management/policies 列表/创建/删除/AI 建议，运行时按策略指纹热重建引擎
• MCP 网关：支持 stdio / HTTP / SSE，platform MCP 暴露 33 个工具（11 领域 × suggest/validate/compile），调用者身份由网关注入
• Guardrails：Pre/Post-call 检查，动作 block/mask/log/allow，覆盖 PII、提示注入、内容审核、敏感词
• 运维与工业协议：备份/恢复（dry-run/apply、审批签名）、健康检查三端点；B2MML 17 套模板 + XSD、ISA-95 能力发现

能力边界：工具级写入确认与 Saga 回滚由 Orchidea Guard 提供，不在 Gateway 核心实现内。

核心特性

🌐 100+ Provider 统一接入

• 云厂商：OpenAI、Anthropic Claude、Google Gemini、Azure OpenAI、AWS Bedrock、Cohere、Mistral AI、Groq、DeepSeek、Moonshot、Together AI、Vertex AI、Watsonx、Snowflake Cortex、Gigachat、Nomic、OpenRouter、Fireworks AI、SambaNova、Predibase、Triton …
• 开源推理：Ollama、vLLM、HuggingFace TGI、Llama.cpp、TensorRT-LLM、SGLang、LM Studio、Llamafile、Text Generation Inference …
• AES-256-GCM 密钥加密存储，支持 HashiCorp Vault / AWS Secrets Manager / Azure Key Vault / GCP Secret Manager 外部托管

🛣️ 智能路由（12 种策略）

simple · weighted-priority · latency-based · cost-based · rate-limit-aware · content-filtering · least-busy · semantic-cache · fallback · retry · load-balancing · custom

🔐 企业级认证与授权

• 虚拟密钥（Virtual Key）签发，支持自动轮换/分阶段作废/IP 白名单
• RBAC 权限：管理员 / 团队管理员 / 开发者 / 审计员
• SSO：OIDC（企业微信/钉钉/飞书/Okta/Azure AD）· SAML 2.0 · LDAP
• SCIM v2 用户同步（/scim/v2/*，application/scim+json）

🛡️ Guardrails 内容安全

• 输入/输出 PII 检测与脱敏（手机号/身份证/邮箱/银行卡）
• 敏感词过滤、语义级拦截、自定义规则引擎
• MCP Guardrails、护栏回退策略、实时评估

💰 成本追踪与预算控制

• Token 级别成本归因（Key/Team/Org/Model/Tag）
• 多窗口预算（日/周/月/季），告警 + 熔断
• 供应商折扣矩阵、成本预估、账单导出（CSV/PDF）

🏭 工业互联网集成（ISA-95）

• B2MML 路由：/api/v1/b2mml/* — 生产工单（WorkSchedule）、工单回报（WorkResponse）、工艺定义（WorkDefinition）、物料定义（MaterialDefinition）、设备主数据（Equipment）
• ISA-95 网关：/api/v1/isa95/* — 能力发现、健康探活、B2MML/Sparkplug/AAS 多协议
• 17 套 B2MML 模板，XSD 严格字段顺序校验

🔧 MCP 工具生态

• MCP 客户端库 + FastAPI 工具集路由（/v1/mcp/toolsets/*）
• OAuth 授权、AWS SigV4 认证、提示词市场、资源 API
• 技能市场（/v1/skills/*）、Kingdee 金蝶工具集、Digiwin 鼎捷集成预留

🌍 多语言国际化（i18n）

• 中文 / 英文 双语界面与 API
• 语言检测：URL 参数 → Cookie → Accept-Language 头
• 线程安全上下文、语言回退、动态热加载

📊 可观测性

• Prometheus 指标（/metrics）、Grafana 仪表盘
• OpenTelemetry 全链路追踪
• 日志集成：Langfuse · Langsmith · Helicone · S3 · GCS · DynamoDB · MLflow · W&B · Slack 告警
• 审计日志（/v1/audit/logs、/v1/audit/stats），操作留痕，合规导出

⚙️ 前端管理后台（UI-Admin）

• 21 个页面：Dashboard / Playground / 模型 / 密钥 / 团队 / 组织 / 用户 / 护栏 / 策略 / 成本 / 用量 / 操作 / 运维 / 设置 / 监控 …
• 天智兰心设计系统（Design Tokens：--sys-* / --ref-* / --btn-*）
• 暗黑模式（data-theme="dark"）、完整 CSS 变量体系
• 语言切换器、移动端响应式布局

架构概览

                      ┌─────────────────────────────────────────────────────┐
  客户端 SDK ──────►│              Orchidea-Gateway  (:4000)                │
                      │  ┌────────────────────────────────────────────────┐  │
  MCP 客户端 ───────►│  │  Middleware: CORS · i18n · Audit · Telemetry    │  │
                      │  └───────────────────────┬────────────────────────┘  │
  B2MML (ISA-95) ───►│                          ▼                           │
                      │  ┌────────────────────────────────────────────────┐  │
                      │  │  Auth & RBAC: 虚拟密钥 · SSO · SCIM · IP 白名单│  │
                      │  └───────────────────────┬────────────────────────┘  │
                      │                          ▼                           │
                      │  ┌────────────────────────────────────────────────┐  │
                      │  │  Router: 12 策略 · 熔断 · 重试 · 故障转移      │  │
                      │  └───────────────────────┬────────────────────────┘  │
                      │                          ▼                           │
                      │  ┌─────────────────────┐ ┌────────────────────────┐  │
                      │  │ Guardrails: PII/敏感│ │ Cache: 语义·Dual·预热    │  │
                      │  └─────────────────────┘ └────────────────────────┘  │
                      │                          ▼                           │
                      │  ┌────────────────────────────────────────────────┐  │
                      │  │  Spend Tracking: 归因 · 预算 · 告警 · 报表     │  │
                      │  └───────────────────────┬────────────────────────┘  │
                      └──────────────────────────┼───────────────────────────┘
                                                 ▼
     ┌─────────────┬───────────────┬──────────────┬──────────────┐
     │ PostgreSQL  │    Redis      │  100+ Provider │ MCP / B2MML  │
     │  + pgvector │   + Semantic  │  (OpenAI/云/开源)│ / Kingdee…  │
     └─────────────┴───────────────┴──────────────┴──────────────┘

快速开始

0. 环境要求

• Python 3.11+
• PostgreSQL 15+（可选，开启成本追踪需启用）
• Redis 7+（可选，开启缓存/限流需启用）
• 至少 4 核 / 8 GB 内存

1. 克隆与安装

git clone <your-orchidea-repo> orchidea-gateway
cd orchidea-gateway/orchidea-gateway

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

2. 配置环境变量

cp .env.example .env

最小可用配置（仅需接入 1 个模型 Provider）：

# 1. 基础
PORT=4000
DEBUG=false
DEFAULT_LANGUAGE=zh

# 2. 安全
JWT_SECRET_KEY=change-this-to-a-32-char-random-string
GATEWAY_ADMIN_USERNAME=admin
GATEWAY_ADMIN_PASSWORD=change-this-admin-password

# 3. 默认模型
GATEWAY_PROXY_MASTER_KEY=sk-orchidea-xxxx-your-global-master-key
DEFAULT_MODEL=gpt-4o
OPENAI_API_KEY=sk-proj-xxxx-your-openai-key

生产环境必须启用：ENFORCE_STRONG_JWT_SECRET=true、ADMIN_BOOTSTRAP_FORCE=false、ADMIN_COOKIE_SECURE=true。

3. 启动服务

python main.py

4. 验证服务

# 健康检查
curl http://localhost:4000/health

# 模型列表（需 master key）
curl -H "Authorization: Bearer sk-orchidea-xxxx" http://localhost:4000/v1/models

5. 登录后台

• 管理后台：http://localhost:4000/ui-admin/
• 管理员账号：.env 中配置的 GATEWAY_ADMIN_USERNAME / GATEWAY_ADMIN_PASSWORD
• Swagger 文档：http://localhost:4000/docs?lang=zh
• ReDoc 文档：http://localhost:4000/redoc?lang=en

6. 第一行代码

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:4000/v1",
    api_key="sk-orchidea-xxxx-your-key",
)

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "介绍一下 Orchidea-Gateway"}],
)
print(resp.choices[0].message.content)

Docker 一键启动

cp .env.example .env      # 修改至少 JWT_SECRET_KEY / 管理员密码
docker compose up -d      # 启动 gateway + postgres + redis
docker compose logs -f    # 查看日志

访问 http://localhost:4000/health 验证。

Kubernetes / Helm 部署

Chart 位于 k8s/helm/orchidea/：

helm dependency update k8s/helm/orchidea
helm upgrade --install orchidea-gateway k8s/helm/orchidea \
  --namespace orchidea --create-namespace \
  --set gateway.env.PORT="4000" \
  --set gateway.masterKey="$GATEWAY_PROXY_MASTER_KEY" \
  --set gateway.jwtSecret="$JWT_SECRET_KEY" \
  --set gateway.adminPassword="$GATEWAY_ADMIN_PASSWORD"

kubectl get hpa -n orchidea     # 自动扩缩容
kubectl get ingress -n orchidea # 入口

HPA 默认 3 副本，自动扩缩容指标：CPU 70% / 内存 75%。

项目结构

orchidea-gateway/
├── main.py                      # ★ 主入口 (~1900 行)
├── .env.example                 # 环境变量模板 (100+ 配置项)
├── requirements.txt             # Python 依赖
├── docker-compose.yml           # 本地容器编排
│
├── i18n/                        # 国际化
│   ├── core.py / middleware.py / detector.py / setup.py
│   └── locales/{zh,en}.json     # 83 个翻译键
│
├── b2mml/                       # ISA-95 B2MML 工业协议
│   ├── router.py / server.py / parser.py / generator.py
│   ├── templates/               # 17 套 B2MML XML 模板
│   └── skills/                  # 3 个 B2MML MCP 技能
│
├── routes/                      # 顶层路由
│   └── isa95_gateway.py         # /api/v1/isa95/*
│
├── batch0-architecture/         # 架构本体 (DDD/SDD/OWL)
│   ├── orchidea-architecture.md
│   ├── api-contracts.yaml       # OpenAPI 3.1 契约
│   ├── ontology.ttl             # 本体定义 (OWL/RDF)
│   ├── schema.sql               # PostgreSQL Schema
│   └── sdd-standards.md
│
├── batch1-data/                 # 数据基础设施
│   ├── db.py                    # PostgreSQL / Redis 连接池
│   ├── repositories/            # 仓储层 (audit/spend/…)
│   ├── migrations/              # 数据库变更脚本
│   └── *.sql                    # 初始化/索引/分区
│
├── batch2-providers/            # Provider 适配层 (100+ 模型)
│   ├── providers/
│   │   ├── base.py              # BaseLLM 抽象基类
│   │   ├── cloud/               # 97 个云 Provider
│   │   └── opensource/          # 开源推理引擎
│   └── provider_registry.py     # 工厂注册器
│
├── batch3-gateway/              # ★ 网关核心
│   ├── management_endpoints/    # 34 文件，27+ 管理路由
│   ├── auth/                    # 密钥/SSO/SCIM/短信/加密
│   ├── proxy/                   # 代理转发/补全/健康检查
│   ├── router/                  # 12 种路由策略
│   ├── cache/                   # 语义/内存/Redis 缓存
│   ├── cost_tracking/           # 成本归因/预算/供应商折扣
│   ├── guardrails/ + guardrails_endpoints.py
│   ├── vector_stores/           # pgvector / S3 / 本地
│   ├── assistants/ / fine_tuning/ / files/ / interactions/
│   ├── evals/ / rag/ / analytics_endpoints/
│   ├── images/ / audio/ / rerank/ / responses/ / realtime/
│   ├── branding/ / discovery_endpoints/
│   ├── callbacks/ / hooks/ / websocket/
│   ├── monitoring/ / observability_config/
│   ├── debugging_endpoints/ / utils/
│   └── config/ / policy_engine/ / docs/ / health_endpoints/
│
├── batch4-mcp/                  # MCP 工具协议
│   ├── mcp/                     # client / toolsets / prompts / resources / oauth / aws-sigv4
│   ├── guardrails/              # MCP Guardrails + Fallbacks
│   ├── skills/                  # 3 个技能 (add-key/add-model/view-usage)
│   └── tools/                   # kingdee / digiwin / generic
│
├── batch5-frontend/             # 前端
│   └── ui-admin/                # React + TS + Vite，21 页面
│       └── src/
│           ├── pages/           # Dashboard/Playground/Models/Keys/Teams…
│           ├── components/      # Layout · LanguageSwitcher
│           ├── services/api.ts  # 85 个 API 封装
│           ├── i18n/index.ts    # 前端国际化
│           └── index.css        # Design Tokens (orch- BEM 类)
│
├── batch6-testing/              # 测试套件
│   ├── observatory/server.py    # 测试编排 / Slack 通知
│   ├── tests/                   # 单元 / 集成 / 安全 / lint
│   └── .github/workflows/ci-cd.yml
│
├── k8s/                         # Kubernetes 部署
│   ├── helm/orchidea/           # Helm Chart (deployment/svc/ingress/hpa)
│   └── hpa.yaml
│
├── UI.md                        # 天智兰心 UI 设计系统 V2.0
└── copy.md                      # 洁净复刻工程 SOP

关键环境变量（生产部署）

完整列表见 .env.example。

API 速览

完整契约参考 batch0-architecture/api-contracts.yaml。

设计规范

品牌约定速查

文档索引

技术栈

许可证

© Orchidea AI 保留所有权利。本项目遵循 Orchidea 内部许可协议。