5分钟极速起步

一、 快速启动：Docker 最简模式（内置 SQLite）

OmniCortex 支持以极简的单容器模式快速拉起。系统默认内置 SQLite 嵌入式存储引擎，无需提前安装或配置外部 PostgreSQL 或 Redis，一条命令即可完成网关启动与数据持久化。

1. 单容器极速启动

运行以下 Docker 命令拉起 OmniCortex 网关服务：

docker run -d \
  --name omnicortex-gateway \
  -p 8080:8080 \
  -v $(pwd)/data:/app/data \
  omnicortex/gateway:latest

参数说明：

• -p 8080:8080：将容器的 8080 端口映射到宿主机，该端口同时承载企业管理控制台（Web Console）与标准 API 流量。
• -v $(pwd)/data:/app/data：挂载当前目录下的 data 文件夹至容器内部数据目录。系统将自动在该目录下创建并维护 SQLite 数据库（config.db 与 logs.db），确保所有控制台配置与调用日志在容器重启后不丢失。

⚠️ 适用场景说明

内置 SQLite 模式仅适用于本地功能体验、极速上手验证与轻量测试（PoC）。
由于 SQLite 在高并发读写锁及多节点水平扩展上的天然限制，生产环境或多节点高可用集群部署，请采用外置 PostgreSQL 数据库作为配置中心与日志存储后端。

---

二、 大模型接入实战：4 步极速闭环

通过 OmniCortex 纳管与调用大模型，仅需完成四步操作即可达成业务端闭环。

第 1 步：添加供应商和供应商密钥

在网关中登记上游真实的模型服务商凭据。

1. 登录控制台，导航进入 「模型与治理」 → 「模型供应商 (Model Providers)」。
2. 在左侧点击 「+ 添加供应商」 下拉菜单，选择目标厂商（例如 DeepSeek、OpenAI、Anthropic，或自建的 vLLM / Ollama 开源算力池）。
3. 在右侧详情中进入 「密钥管理 (Keys)」 标签页，点击 「+ 添加密钥」 抽屉，填入密钥别名与真实 API Key（支持明文录入或使用 env.DEEPSEEK_API_KEY 等环境变量表达式）。
4. 点击保存，确认卡片状态显示为 「在线 (Online)」。

第 2 步：添加模型访问策略（可选）

为多业务团队统筹定义模型权限集与调用配额。

1. 导航进入 「模型与治理」 → 「模型访问策略 (Access Profiles)」。
2. 点击右上角 「+ 新建策略」，填写策略名称（如 通用大模型调用策略）。
3. 在「供应商路由与模型准入」中点击 「+ 添加供应商...」 选择目标厂商，勾选授权模型白名单（如勾选 * (允许全部模型) 或填入指定模型）。
4. 点击保存。

💡 什么是模型访问策略？为什么它是可选的？

• 本质定义：模型访问策略是企业级可复用的“权限与流量套餐模板”。它将允许调用的模型资产、速率配额与降级规则打包为一个标准化策略实体。
• 为什么可选：如果只是为了快速进行技术验证或单业务测试，您可以跳过此步，直接在第 3 步创建虚拟密钥时单独勾选模型；但当企业内部有多个应用或业务线时，创建访问策略可以让多个虚拟密钥直接继承相同的配置，无需为每个密钥重复设置可用模型和限制规则。

第 3 步：创建虚拟密钥 (Virtual Key)

派发与上游真实 Key 物理物理解耦的业务端调用凭证。

1. 导航进入 「模型与治理」 → 「虚拟密钥 (Virtual Keys)」。
2. 点击右上角 「+ 新建虚拟密钥」 抽屉，填写密钥名称（如 sk-quickstart-demo）并绑定团队。
3. 选择关联在第 2 步创建的「模型访问策略」（或直接手动指定可用模型）。
4. 点击创建，复制生成的以 sk- 开头的虚拟密钥字符串并妥善保存。

IMPORTANT

真实密钥物理隔离：外部业务系统、前端应用以及第三方平台仅能接触到该「虚拟密钥」，上游云厂商的真实商业凭据被安全物理隔离在网关内核中，彻底杜绝敏感 Key 泄漏风险。

第 4 步：在模型调试中心测试（可选）

无需编写代码，直接在控制台演练场中验证模型连通性与交互质量：

1. 导航进入 「开发者工作区」 → 「模型调试中心 (Model Playground)」。
2. 在顶部选择刚创建的虚拟密钥与目标模型，开启流式传输（Stream）。
3. 在左侧输入测试提示词（如 "你好，请简要介绍一下你自己"），点击顶部 「发送请求」。
4. 右侧诊断终端将实时呈现流式打字输出与模型思考过程；亦可直接点击终端右上角 「查看审计」（或前往 「可观测中心」 → 「LLM运行日志」）秒级查验本次调用的 Token 消耗与端到端耗时详情。

📸 截图替换指引（模型调试中心）

• 替换路径：建议保存至 Documentation/docs/public/images/quickstart/zh/model-playground-success.png（中文版覆盖），系统默认兜底回退至 en/ 目录。
• 推荐尺寸：1920×1080 或 16:9 高清比例（推荐 Dark OLED 深色模式）。
• 关键画面要素：
  1. 顶部配置栏清晰展示选中的虚拟密钥（如 sk-quickstart-demo）与目标模型；
  2. 左侧输入测试 Prompt（如 "你好，请简要介绍一下你自己"）；
  3. 右侧诊断输出终端展示正在流式打字或已完成输出的完整回答，以及右上角附带的 Token 消耗统计。

---

三、 安全围栏：4 步防护实战

在多业务生产调用中，为了防范提示词越狱注入攻击（Jailbreak）以及敏感隐私数据（PII）泄露，只需 4 步即可快速建立企业级安全防护闭环。

第 1 步：配置和启用引擎 (Engines)

1. 导航进入 「安全围栏」 → 「检测能力库 (Capabilities)」。
2. 查验系统内置的各类安全引擎驱动状态（如正则表达式引擎、PII 隐私脱敏引擎等），确保目标引擎处于启用状态。

第 2 步：创建模型策略包 (Policy Pack)

以常用的正则表达式策略包（Regex Policy Pack）为例：

1. 导航进入 「安全围栏」 → 「检测能力库 (Capabilities)」。
2. 在左侧列表中选中 regex（正则表达式引擎），在右侧主区域切换至 「策略包 (Templates)」 选项卡。
3. 点击 「+ 新建策略包」，输入策略包名称（如 敏感数据正则防护包）。
4. 在规则组装区域点击 「选择规则」，从系统内置的规则库中勾选目标规则：
   • 如勾选 中国大陆手机号 (pii.cn_mobile)、居民身份证 (pii.cn_id_card) 等内置规则；
   • 将处置动作设为 「实时阻断 (Block)」（或脱敏 Redact）。
5. 点击确认保存。

💡 什么是模型策略包？

您可以把引擎理解为一个拥有上百条规则的“通用规则池”（包含手机号、身份证、银行卡、邮箱、IP 等各类特征）：

• 按需挑选：在实际业务场景中，一个具体应用往往只需要关注其中的若干条（例如仅需关注 10 条），其余规则无需启用；
• 动作自由配置：在这 10 条规则中，您可以自由定义处置方式——例如将“手机号、邮箱”设为 脱敏 (Redact) 替换为安全掩码，而将“身份证、银行卡”设为 硬阻断 (Block) 拦截；
• 业务解耦复用：基于这种“按需挑选 + 差异化动作”自由组合形成的集合就是「策略包」。企业可以为客服、研发、财务等不同业务线定制各自专属的策略包，供各自的防线按需选择与一键复用。

第 3 步：创建安全防线并配置引流

将策略包编排进防线网络管线，并将业务流量引入防线执行安检。

1. 导航进入 「安全围栏」 → 「防线工作台 (Workbench)」。
2. 在左侧防线目录中点击 「+ 新建防线」 按钮，在弹出的两步创建向导中操作：
   • 向导第 1 步（基础信息）：输入防线名称（如 业务网关默认防线），确认开启防线启用开关；
   • 向导第 2 步（编排策略包）：在穿梭器候选池中，点击将第 2 步创建的 敏感数据正则防护包 添加进防线执行链；
   • 点击提交完成防线创建。
3. 配置引流规则：在右侧防线主工作台的「引流规则 (Assignments)」区域，点击 「+ 添加引流」 抽屉，绑定需要受此防线保护的「虚拟密钥」（如 sk-quickstart-demo）或模型流量。
4. 保存后安全检查即刻在网关请求处理管线中热生效。

💡 什么是安全防线与引流？

如果把“策略包”理解为具体的安全规则模块（如正则敏感词包、越狱防御包），那么「安全防线」与「引流」就是为了让企业能够针对不同业务场景“因地制宜”地实施防护：

• 安全防线是“专属防护围栏”：一条防线可以自由组合来自多个引擎的策略包，并分别控制它们在「用户提问（输入侧）」还是「模型回复（输出侧）」生效，形成一套多层次的安全安检通道；
• 引流是“按业务场景对号入座”：企业内部不同业务线对安全的要求截然不同：
  • 对外公开客服：直面外部访客，风险最高，通常引流至“严苛阻断防线”（强力拦截越狱注入，并对手机号等敏感信息自动脱敏）；
  • 内部研发编程助手：主要用于辅助编码与排错，通常引流至“宽松或仅观察防线”，避免代码中的技术参数被安全策略频繁误杀；
  • 财务与法务系统：涉及商业机密，通常引流至包含账户信息与合同审查的“专项合规防线”。 通过将不同的虚拟密钥、团队或模型流量引流至对应防线，即可实现多业务线各取所需、因地制宜的精细化防护。

第 4 步：在安全围栏调试中心测试（可选）

无需编写代码，直接在控制台安全沙箱中演练验证拦截效果：

1. 导航进入 「开发者工作区」 → 「安全围栏沙箱 (Guardrails Sandbox)」。
2. 选择配置好的防线与模型，输入包含敏感信息的测试文本："用户联系手机是 13800138000，请确认接收"。
3. 沙箱界面将即刻提示请求被安全围栏实时阻断，并高亮展示命中内置的 中国大陆手机号 (pii.cn_mobile) 正则规则。

演练完成后，您亦可前往 「安全围栏」 → 「防线工作台 (Workbench)」 查验全量拦截事件记录与审计留痕。

---

四、 常见问题与快速排障 (Troubleshooting)

异常现象 / 状态码	常见根因分析	推荐解决方案
401 Unauthorized	虚拟密钥未传递、拼写错误或已被停用	检查 HTTP 请求头是否包含 Authorization: Bearer sk-...，并确认该虚拟密钥在控制台处于启用状态
404 Model Not Found	请求的模型未在供应商中纳管，或未加入虚拟密钥白名单	确认请求体中的 model 参数与供应商可用模型一致，并检查虚拟密钥绑定的访问策略是否包含该模型
502 Bad Gateway	网关连接上游模型供应商网络超时或上游凭证失效	在「模型供应商」中点击「连通性测试」，排查上游 API Key 有效性或网络代理配置
安全围栏未发生阻断	防线工作模式被设为「旁路观察 (Observe)」或引流未绑定当前密钥	进入防线设置，确认工作模式切换为「主动拦截 (Enforce)」，并确认引流配置中包含当前虚拟密钥

---

五、 下一步进阶指引

恭喜！您已成功完成了 OmniCortex 网关的极速部署、大模型首调接入与安全围栏防护配置。接下来，您可以继续探索更多企业级深度治理能力：

• 2.2 企业管理控制台导览 (console-tour.md) —— 探索控制台全模块动线、组织工作区与安全中心全景操作；
• 3.1 统一模型资产目录 (model-catalog.md) —— 统一纳管企业内多云商用与私有开源大模型资产；
• 4.4 虚拟密钥隔离体系 (virtual-keys.md) —— 深入了解跨业务线凭证安全隔离与细粒度权限控制；
• 5.1 安全检测引擎矩阵与驱动体系 (engine-matrix.md) —— 全景透视大模型安全检测驱动架构与跨引擎协同防御能力。