企业官网建设流程全解析

1. 项目概述：当“一条命令”不再只是营销话术，而是生产环境里的真实心跳

“一条命令跑起一支 AI 团队”——看到这个标题，我第一反应是皱眉。干了十多年技术一线，从写 Shell 脚本部署 PHP 站点，到用 Ansible 管理上千台边缘设备，再到在 K8s 集群里给大模型服务做灰度发布，我见过太多把“一键部署”包装成银弹的工具。它们往往在 demo 视频里丝滑如德芙，一进真实业务线就卡在权限、网络、模型加载、GPU 显存碎片、日志埋点缺失这五个坎上，最后变成运维同学深夜三点对着 Prometheus 报警发呆的背景音。

但 Octop 1.0 真的不一样。它不是又一个玩具级 CLI 工具，而是一套面向生产环境设计的 AI 助手协同框架。核心关键词“Octop”、“自托管”、“AI助手”、“生产环境”、“Python”，每一个都不是虚词：Octop 是它的名字，也是它的哲学——八爪鱼式弹性伸缩；“自托管”意味着你完全掌控数据主权、模型权重、API 流量和审计日志；“AI助手”在这里不是单点能力，而是可编排、可协作、有角色分工的智能体集群；“生产环境”是它的硬性准入门槛，所有模块默认启用健康检查、请求限流、错误熔断、结构化日志与指标暴露；而 Python，则是它扎根的土壤——不是胶水语言，而是整套调度引擎、协议适配层、本地模型桥接器的主干语言。

它解决的不是“怎么让 AI 说句话”的问题，而是“如何让多个 AI 助手像人类团队一样分工协作、共享上下文、交叉验证、共同交付结果”的系统级难题。比如你在立创 EDA 里做电路设计，Octop 可以同时调度：一个助手读取原理图 JSON 结构并提取关键参数（本地 LLM + 规则引擎），一个助手调用你的私有知识库查 IPC-2221 标准（RAG 模块），一个助手生成 PCB 布局建议（多步推理链），再由一个协调助手整合输出、校验逻辑一致性、生成 Markdown 报告并推送到企业微信——整个流程在单机或 K8s 上，用octop up --env=prod一条命令启动，所有服务自动注册、发现、负载均衡、健康自愈。

适合谁？不是只想跑个 ChatUI 的爱好者，而是正在落地 AI 增效的中小技术团队：你们有明确业务场景（如客服工单分类、合同条款比对、研发文档生成）、有私有数据要保护、有现有 IT 基础设施（Linux 服务器 / K8s 集群）、有 Python 工程能力但不想从零造轮子。Octop 不要求你懂 Transformer 架构，但要求你理解“服务契约”和“可观测性”——它把 AI 工程的复杂性封装成配置项和插件接口，把运维的确定性还给你。

2. 整体架构设计：为什么是“八爪鱼”，而不是“单体应用”或“微服务”

2.1 八爪鱼模型：从单点智能到协同智能的范式跃迁

传统 AI 助手工具（比如早期的 LangChain CLI 或某些开源 Chat UI）本质是“单点智能放大器”：用户输入 → 模型推理 → 输出结果。它解决了“能不能用”的问题，但没解决“怎么用得稳、用得准、用得可持续”的问题。Octop 的核心突破，在于它把“AI 助手”重新定义为可声明、可编排、可治理的服务单元（Agent-as-a-Service, AaaS），其架构天然适配生产环境的四大刚性需求：隔离性、可观测性、弹性、可维护性。

提示：Octop 不是“一个大模型 API 封装器”，而是“一个 AI 助手操作系统”。它不关心你用的是 Qwen2-7B 还是 Phi-3，只关心你提供的助手是否遵循AgentSpec协议——即必须实现init()、invoke(input: dict) -> dict、health_check() -> bool三个方法，并通过标准 HTTP/GRPC 接口暴露。

八爪鱼模型体现在三个层面：

• 物理层（Deployment Topology）：Octop 启动后，会根据octop.yaml配置，自动拉起一组独立进程（非容器，除非你指定 K8s）。每个进程是一个“触手（Tentacle）”，运行一个或多个助手实例。例如：tentacle-eda运行立创 EDA 助手 + IPC 标准查询助手；tentacle-doc运行制度条例学习助手 + PDF 解析助手。它们彼此内存隔离，一个崩溃不影响其他。

• 逻辑层（Orchestration Graph）：Octop 内置轻量级工作流引擎（非 Airflow/Kubeflow），支持 YAML 定义 DAG。比如“合同审核”流程：input → [OCR识别] → [条款抽取] → [风险点比对] → [生成摘要] → [人工复核节点]。每个节点是一个助手，引擎负责传递上下文（带 TTL 的键值存储）、超时控制、重试策略、失败分支跳转。

• 治理层（Control Plane）：Octop 自带一个octopctlCLI 和 Web 控制台（默认:8080）。你可以实时查看每个触手的 CPU/GPU/内存占用、每秒请求数（RPS）、平均延迟、错误率；可以动态启停某个助手、调整其并发数、注入调试日志级别；甚至能回放某次失败请求的完整 trace（从入口网关到最终助手返回，含所有中间状态）。

这种设计直接规避了单体 AI 应用的“一损俱损”风险，也避免了纯微服务架构下服务发现、链路追踪、配置中心等基础设施的沉重负担——Octop 把这些都内置了，且默认开箱即用。

2.2 为什么选择 Python 作为主干语言：不是妥协，而是深思熟虑的工程权衡

看到“Python”这个词，很多老司机第一反应是“性能瓶颈”“GIL 锁死”“不适合高并发”。Octop 用 Python，恰恰是踩过无数坑后的清醒选择：

• 生态即生产力：AI 领域 90% 的模型推理库（llama.cpp, Ollama, vLLM 的 Python client）、向量数据库（Chroma, Qdrant Python SDK）、文档解析（Unstructured, PyPDF2）、RAG 组件（LlamaIndex）都是 Python 原生。如果 Octop 用 Go 或 Rust 重写一遍，光是适配各模型 backend 的连接器就要消耗半年人力，且永远追不上社区更新速度。Octop 的策略是：计算密集型任务（如模型推理）交给专用 backend（Ollama/vLLM），Octop 只做调度、编排、协议转换——这部分 Python 完全够用，且开发效率极高。

• 调试与热重载的确定性：在生产环境中，最怕的不是慢，而是“改了一行代码，重启后行为诡异”。Python 的importlib.reload和丰富的调试器（pdb, debugpy）让 Octop 支持助手代码的热重载——修改eda_assistant.py后，执行octop reload eda_assistant，新版本立刻生效，无需重启整个集群。这对快速迭代业务逻辑至关重要。

• 运维友好性：Python 的venv+requirements.txt是最成熟、最无争议的依赖隔离方案。Octop 的每个触手都运行在独立 venv 中，octop up会自动创建、安装、校验依赖。对比 Docker 镜像构建的漫长等待和缓存失效，pip install -r requirements.txt的确定性更符合中小团队的发布节奏。

当然，它也做了关键优化：Octop 的核心调度器使用asyncio+httpx实现异步 I/O，避免阻塞；对高频调用的内部 API（如健康检查、指标上报）采用内存共享队列（multiprocessing.Queue）而非 HTTP，将 P99 延迟压到 5ms 以内；所有外部模型调用都强制设置timeout=60，防止一个慢请求拖垮整个流水线。

2.3 “自托管”不是口号，而是贯穿设计的七道安全与治理防线

“自托管”常被简化为“自己装在自己服务器上”。Octop 的自托管，是七个维度的纵深防御：

1. 数据主权：所有用户上传文件（PDF/DOCX/图片）默认存于本地./data/uploads，经 SHA256 哈希后命名，绝不上传至任何第三方。OCR 结果、向量化 Embedding、RAG 索引全部落盘在本地 SQLite 或你指定的 PostgreSQL。

2. 模型主权：Octop 不提供任何模型下载链接。它只集成 Ollama、vLLM、Text Generation Inference（TGI）等主流 backend 的标准 API。你用ollama run qwen2:7b下载的模型，Octop 直接调用http://localhost:11434/api/chat，全程不碰模型权重文件。

3. 网络主权：Octop 默认绑定127.0.0.1:8000，拒绝外网访问。若需公网暴露，必须显式配置--host=0.0.0.0并启用反向代理（Nginx/Caddy）做 TLS 终止和基础鉴权。它不内置用户管理系统，但提供/auth/webhook接口，让你对接 LDAP、OAuth2 或自有 SSO。

4. 配置主权：所有配置（助手定义、工作流、backend 地址、限流规则）均来自octop.yaml，文本可 Git 版本管理。没有隐藏的数据库配置表，没有运行时修改的后台页面。

5. 日志主权：日志默认输出到./logs/octop.log，格式为 JSON，包含timestamp,level,service,tentacle,agent,trace_id,request_id,message。可一键对接 ELK 或 Loki，但绝不强制。

6. 指标主权：Prometheus metrics 端点/metrics暴露标准指标（octop_agent_requests_total,octop_agent_duration_seconds），但不内置 Pushgateway。你爱推到哪就推到哪。

7. 升级主权：octop upgrade命令只更新 Octop 自身二进制和核心库，绝不触碰你的助手代码、模型文件、数据目录。升级失败自动回滚到上一版本。

这七道防线，让 Octop 在金融、政务、制造业等对数据合规要求极高的场景中，真正具备了落地资格。它不假设你有云厂商的 IAM 体系，也不假设你有专职 SRE，而是把治理权交还给技术负责人。

3. 核心细节解析：从octop up到第一个助手上线的 17 分钟实操

3.1 环境准备：三步筑基，拒绝“在我机器上能跑”

Octop 对环境的要求极其务实：一台能跑 Python 3.10+ 的 Linux 机器（推荐 Ubuntu 22.04 / CentOS 8+），4GB 内存起步（跑小模型），有 GPU 更佳（但非必需）。我们以 Ubuntu 22.04 为例，走一遍真实部署：

第一步：安装 Python 3.11（官方推荐版本）

# 更新源并安装依赖 sudo apt update && sudo apt install -y software-properties-common curl # 添加 deadsnakes PPA（Ubuntu 官方不提供 3.11） sudo add-apt-repository ppa:deadsnakes/ppa -y sudo apt update sudo apt install -y python3.11 python3.11-venv python3.11-dev # 设置默认 python3 指向 3.11（谨慎操作，确认不影响系统脚本） sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 1 sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 2 sudo update-alternatives --config python3 # 选择 3.11

注意：不要用apt install python3，Ubuntu 22.04 默认是 3.10，而 Octop 1.0 的pydantic v2和httpx强依赖 3.11 的新特性。我试过强行降级依赖，结果在octopctl status时因typing.Union解析失败直接 panic。

第二步：安装模型 backend（选一个，推荐 Ollama）

# 一行安装 Ollama（官方脚本，已验证） curl -fsSL https://ollama.com/install.sh | sh # 启动 Ollama 服务 systemctl --user start ollama # 加入开机自启（重要！否则 Octop 启动时找不到 backend） systemctl --user enable ollama # 下载一个轻量模型用于测试（Qwen2-0.5B 或 Phi-3-mini） ollama run qwen2:0.5b # 此时你会看到模型加载完成，Ollama 默认监听 http://127.0.0.1:11434

实操心得：Ollama 是新手最友好的选择，它自动处理 CUDA/cuDNN 版本匹配、模型量化、内存映射。如果你用 vLLM，需要手动pip install vllm并python -m vllm.entrypoints.api_server --model Qwen2-0.5B --tensor-parallel-size 1，端口默认8000，Octop 配置里要改成http://localhost:8000。

第三步：初始化 Octop 项目

# 创建项目目录 mkdir my-ai-team && cd my-ai-team # 初始化（会生成 octop.yaml 和 agents/ 目录） octop init # 查看生成的结构 tree -L 2 # . # ├── octop.yaml # 主配置文件 # ├── agents/ # 所有助手代码存放处 # │ ├── __init__.py # │ └── hello_world.py # 示例助手 # └── logs/ # 日志目录（首次启动时创建）

octop init不是魔法，它只是复制了一份精简的模板。octop.yaml是核心，我们打开看看：

# octop.yaml version: "1.0" name: "my-ai-team" environment: "dev" # 可设为 prod，触发更严格的健康检查 # 全局 backend 配置 backends: default: "ollama" # 默认用 ollama ollama: url: "http://127.0.0.1:11434" timeout: 120 vllm: url: "http://127.0.0.1:8000" timeout: 120 # 定义助手（Agents） agents: - name: "hello-world" description: "一个打招呼的示例助手" module: "agents.hello_world" class: "HelloWorldAgent" backend: "ollama" model: "qwen2:0.5b" # 必须是 ollama list 里存在的名字 concurrency: 2 # 最大并发请求数 timeout: 30 # 单次调用超时（秒） # 工作流（Orchestration） workflows: - name: "greet-user" description: "简单问候流程" steps: - agent: "hello-world" input_map: {"user_name": "input.user_name"}

这个 YAML 文件就是 Octop 的“宪法”。它声明了：有哪些助手、用什么模型、并发多少、超时多久、以及它们如何组合。没有 XML，没有 JSON Schema，就是干净的 YAML。

3.2 编写第一个助手：从hello_world.py看清协议本质

agents/hello_world.py是 Octop 的“Hello World”，但它远不止打印字符串。我们逐行解析其设计意图：

# agents/hello_world.py from octop.agent import BaseAgent # 必须继承 BaseAgent from octop.types import AgentInput, AgentOutput # 类型提示，非强制但强烈推荐 class HelloWorldAgent(BaseAgent): """ 一个符合 Octop AgentSpec 协议的最小可行助手。 它证明了：助手 = 初始化逻辑 + 一次调用逻辑 + 健康检查逻辑 """ def init(self) -> None: """ 初始化方法：在助手进程启动时执行一次。 这里可以加载本地知识库、初始化数据库连接、预热模型等。 注意：此方法在进程启动时同步执行，耗时过长会阻塞整个触手。 """ # 示例：加载一个本地 JSON 知识库（模拟私有数据） import json try: with open("./data/company_info.json", "r") as f: self.company_info = json.load(f) except FileNotFoundError: self.company_info = {"name": "My Company", "slogan": "AI for Everyone"} def invoke(self, input: AgentInput) -> AgentOutput: """ 核心调用方法：每次收到请求时执行。 input: dict，由工作流引擎传入，结构由 workflow.steps.input_map 决定 output: dict，必须包含 'response' 字段，其他字段可自定义（如 'confidence', 'sources'） """ # 1. 提取输入参数（健壮性处理） user_name = input.get("user_name", "there") greeting_style = input.get("style", "friendly") # 2. 调用本地模型（Ollama backend 会自动处理） # Octop 会将此调用转发给 ollama，传入 system prompt 和 user message response = self.llm.chat( messages=[ {"role": "system", "content": f"你是一家叫 {self.company_info['name']} 的公司助手，口号是 {self.company_info['slogan']}。请用 {greeting_style} 的风格打招呼。"}, {"role": "user", "content": f"你好，我是{user_name}。"} ], model=self.config.model, # 从 octop.yaml 读取 options={"temperature": 0.3} ) # 3. 构建结构化输出（供下游助手或前端消费） return { "response": response["message"]["content"], "company_name": self.company_info["name"], "greeting_style_used": greeting_style, "backend_latency_ms": response.get("eval_duration", 0) // 1000000 # Ollama 返回的纳秒级延迟 } def health_check(self) -> bool: """ 健康检查方法：Octop 每 10 秒调用一次，决定是否将该助手从负载均衡池中剔除。 必须快速返回（< 1s），不能做重 IO。 这里我们检查：Ollama 是否可达 + 本地知识库是否加载成功。 """ import requests try: # 检查 Ollama resp = requests.get(f"{self.config.backend.url}/api/tags", timeout=2) if resp.status_code != 200: return False # 检查知识库 if not hasattr(self, "company_info"): return False return True except Exception: return False

这段代码揭示了 Octop 的核心契约：

• init()是“上岗前培训”，确保助手准备好；
• invoke()是“上岗后干活”，输入输出严格结构化；
• health_check()是“上岗后体检”，保证服务可用。

实操心得：很多新手在invoke()里写time.sleep(5)模拟耗时操作，结果导致整个触手的并发数被占满。正确做法是：耗时操作（如调用外部 API、大文件处理）必须用asyncio.to_thread()或concurrent.futures.ThreadPoolExecutor包装，否则会阻塞事件循环。Octop 的self.llm.chat()方法内部已做异步封装，你无需操心。

3.3 启动与验证：octop up的 17 分钟发生了什么

现在，执行那条改变一切的命令：

octop up --env=prod

这 17 分钟（实际通常 < 60 秒，17 分钟是包含阅读日志、理解过程的时间），Octop 在后台完成了以下动作：

第 1-10 秒：解析与校验

• 读取octop.yaml，校验 YAML 语法、必填字段（name,agents[*].name,agents[*].module）；
• 检查agents/目录下所有.py文件能否被import（即agents.hello_world是否存在）；
• 验证backends配置的 URL 是否可达（GET/api/tags）；
• 检查agents[*].model是否在 Ollama 的list中（调用ollama list）。

第 10-30 秒：进程孵化与初始化

• 启动主进程（octop-core），监听:8000（HTTP API）和:8080（Web 控制台）；
• 为每个agents条目 fork 一个子进程（tentacle），每个子进程：
  • 创建独立venv（如果--isolated参数开启）；
  • import对应的助手模块（如agents.hello_world）；
  • 调用HelloWorldAgent().init()，加载知识库；
  • 注册到主进程的进程管理器。

第 30-60 秒：服务注册与健康探活

• 每个触手进程启动一个 HTTP server（:8001,:8002...），暴露/health和/invoke；
• 主进程通过http://127.0.0.1:8001/health轮询所有触手；
• 所有触手返回200 OK后，主进程将它们加入内部服务发现列表；
• 同时，启动 Prometheus metrics exporter，暴露/metrics。

第 60 秒后：就绪待命

• 打开浏览器访问http://localhost:8080，看到 Web 控制台，显示hello-world助手状态为Healthy，RPS 为0；
• 在终端用 curl 测试：

  curl -X POST http://localhost:8000/workflows/greet-user \ -H "Content-Type: application/json" \ -d '{"user_name": "张三", "style": "professional"}' # 返回： # {"response":"您好，张三！我是My Company的AI助手，口号是AI for Everyone。很高兴为您服务。","company_name":"My Company","greeting_style_used":"professional","backend_latency_ms":1245}

整个过程没有 Docker、没有 Kubernetes YAML、没有 Helm Chart。它就是一个 Python 进程树，用最朴素的方式，实现了生产级的弹性与可观测性。

4. 生产环境深度实践：从单机到 K8s，从测试到上线的避坑指南

4.1 单机生产部署：四条铁律与两个致命陷阱

在客户现场，我见过太多团队把 Octop 当成玩具，在测试机上跑通就直接上生产。结果在正式环境栽了跟头。以下是我在 7 个客户现场总结出的四条铁律：

铁律一：永远不要用 root 用户运行octop up

• 后果：octop.yaml里若配置了./data/uploads，root 创建的文件，后续普通用户无法删除；Ollama 的 socket 文件权限混乱；日志文件属主为 root，Logrotate 失败。
• 正确做法：创建专用用户octop-user，chown -R octop-user:octop-user /opt/octop，然后sudo -u octop-user octop up。

铁律二：--env=prod不是开关，而是一组强制约束

• 启用--env=prod后，Octop 会：
  • 禁用所有调试端点（如/debug/pprof）；
  • 强制所有助手concurrency >= 1（不允许为 0）；
  • 启用请求限流（默认 100 RPS per agent，可配）；
  • 日志级别强制为INFO，屏蔽DEBUG；
  • 健康检查失败 3 次后，自动 kill 该触手进程并重启。
• 如果你跳过这一步，等于在生产环境裸奔。

铁律三：模型路径必须绝对化，且 octop-user 有读取权限

• 错误配置：model: "qwen2:0.5b"（Ollama 默认路径/home/username/.ollama/models）
• 问题：octop-user的 home 目录是/home/octop-user，但 Ollama 服务是root启动的，模型文件在/root/.ollama/models，权限为700，octop-user无法访问。
• 正确做法：ollama serve时指定OLLAMA_MODELS=/opt/ollama/models，然后chown -R octop-user:octop-user /opt/ollama/models，octop.yaml中backends.ollama.url改为http://127.0.0.1:11434。

铁律四：备份octop.yaml和agents/目录，比备份模型更重要

• 模型可以重下，但你的助手逻辑、工作流编排、业务规则，全在octop.yaml和agents/*.py里。我有个客户删了agents/目录，以为重octop init就能恢复，结果所有定制化逻辑全丢。现在他们用git commit -m "prod deploy"作为上线前最后一步。

两个致命陷阱：

• 陷阱一：忽略ulimit -n（文件描述符限制）

  • 现象：运行 2 小时后，新请求全部503 Service Unavailable，日志里全是OSError: [Errno 24] Too many open files。
  • 原因：每个触手进程、每个 HTTP 连接、每个 Ollama 的 streaming response，都占用一个 fd。默认ulimit -n是 1024，Octop 一个触手就可能开 200+ fd。
  • 解决：sudo systemctl edit octop.service，添加：

    [Service] LimitNOFILE=65536

    然后sudo systemctl daemon-reload && sudo systemctl restart octop。

• 陷阱二：在invoke()里做同步文件 IO

  • 现象：hello-world助手响应时间从 200ms 涨到 5s，P99 延迟飙升，octopctl status显示pending_requests持续增长。
  • 原因：invoke()是异步函数，但open("large_file.pdf", "rb").read()是同步阻塞调用，会卡住整个 asyncio event loop。
  • 解决：用await asyncio.to_thread(open, "large_file.pdf", "rb")，或更优：把文件读取移到init()里预加载，或用aiofiles库。

4.2 K8s 生产部署：用 3 个 YAML 文件替代 200 行 Helm Chart

Octop 官方不提供 Helm Chart，因为它认为 K8s 部署应该足够简单。我用 3 个原生 YAML 文件，在客户的 K8s 集群（v1.24+）上完成了零故障上线：

文件一：octop-configmap.yaml（配置即代码）

apiVersion: v1 kind: ConfigMap metadata: name: octop-config data: octop.yaml: | version: "1.0" name: "eda-team-prod" environment: "prod" backends: default: "ollama" ollama: url: "http://ollama-service.default.svc.cluster.local:11434" timeout: 120 agents: - name: "eda-parser" module: "agents.eda_parser" class: "EDAParserAgent" backend: "ollama" model: "qwen2:1.5b" concurrency: 4 - name: "ipc-checker" module: "agents.ipc_checker" class: "IPCCheckerAgent" backend: "ollama" model: "phi3:3.8b" concurrency: 2 workflows: - name: "analyze-schematic" steps: - agent: "eda-parser" input_map: {"schematic_json": "input.schematic_json"} - agent: "ipc-checker" input_map: {"parsed_data": "prev.response.parsed_data"} --- apiVersion: v1 kind: Secret metadata: name: octop-secrets type: Opaque data: # base64 encoded, e.g., echo -n "my-api-key" | base64 api_key: bXktYXBpLWtleQ==

关键点：octop.yaml里backends.ollama.url指向 K8s Service 名，而非localhost。Secret 用于存敏感配置，agents/*.py代码里用os.getenv("API_KEY")读取。

文件二：octop-deployment.yaml（无状态服务）

apiVersion: apps/v1 kind: Deployment metadata: name: octop-core spec: replicas: 1 # Octop core 是单点，但高可用靠它自身的健康检查和 K8s livenessProbe selector: matchLabels: app: octop-core template: metadata: labels: app: octop-core spec: containers: - name: octop-core image: ghcr.io/octop/octop:1.0.0 # 官方镜像 ports: - containerPort: 8000 # API - containerPort: 8080 # Web Console volumeMounts: - name: config mountPath: /app/octop.yaml subPath: octop.yaml - name: secrets mountPath: /app/secrets readOnly: true envFrom: - secretRef: name: octop-secrets volumes: - name: config configMap: name: octop-config - name: secrets secret: secretName: octop-secrets # 关键：livenessProbe 直接调用 Octop 自带的健康端点 livenessProbe: httpGet: path: /health port: 8000 initialDelaySeconds: 30 periodSeconds: 10 # readinessProbe 确保所有触手都 healthy 后才接入流量 readinessProbe: exec: command: ["sh", "-c", "octopctl status --json | jq -e '.status == \"healthy\"'"] initialDelaySeconds: 60 periodSeconds: 15

注意：readinessProbe用octopctl status而不是简单的 HTTP GET，因为 Octop 的/readyz端点只检查 core，不检查触手。octopctl status会返回 JSON，包含所有触手的健康状态。

文件三：octop-service.yaml（服务暴露）

apiVersion: v1 kind: Service metadata: name: octop-service spec: selector: app: octop-core ports: - name: api port: 8000 targetPort: 8000 - name: console port: 8080 targetPort: 8080 type: ClusterIP # 内部访问 --- apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: octop-ingress annotations: nginx.ingress.kubernetes.io/ssl-redirect: "true" nginx.ingress.kubernetes.io/proxy-body-size: "50m" # 支持大文件上传 spec: ingressClassName: nginx rules: - host: ai.my-company.com http: paths: - path: / pathType: Prefix backend: service: name: octop-service port: number: 8000 tls: - hosts: - ai.my-company.com secretName: octop-tls-secret

关键配置：proxy-body-size: "50m"是为了支持用户上传大型 PDF/EDA 文件；TLS 终止在 Ingress 层，Octop 内部走 HTTP，简化配置。

这套方案上线后，客户反馈：部署时间从 Helm Chart 的 45 分钟缩短到 8 分钟；故障排查时，kubectl logs -f deploy/octop-core直接看到 Octop 的结构化 JSON 日志，octopctl status一行命令看清所有助手状态，比翻 K8s Events 快 10 倍。

4.3 真实生产问题排查：一份来自凌晨 2 点的故障速查表

在 K8s 集群里，octop up启动后一切正常，但用户反馈“合同审核流程卡在第二步”。我登录服务器，按以下顺序排查（这是我的标准 SOP）：

| 现象 | 快速定位命令 | 根本原因 | 解决