D1 业务全景与开发环境

精讲（必讲）。本模块是全部培训的"地图"。

教学目标（学完能做什么）

能用自己的话说出公司主营业务与盈利链路（上游密钥 → 中游网关 → 下游客户）
能画出业务架构图，并标注 sub2api / newapi / oneapi 各自的角色
能说出公司核心服务的名称、域名、技术栈，以及"哪一个是咱们的饭碗"
能独立完成开发环境搭建（SSH key、工具链、克隆仓库）
理解 AGENTS.md/CLAUDE.md 操作分级，知道"新人红线"

前置要求

无（第一天，从零开始）

本模块在业务中的位置

本模块本身就是整张地图，后续所有模块都是这张图上的一个点。

内容分段

1. 公司业务模型：Claude token 销售

什么是 token：LLM 计费的最小单位。1 token ≈ 0.75 个英文单词，中文大约 1 个汉字 ≈ 1~2 token。每次调用 = 输入 token + 输出 token，都计费。
商业模式：上游批量持有 Claude 端点的调用能力（key + base_url），通过自建网关转售给下游客户（用 Claude Code 的用户、调用 API 的用户），按 token 计费赚取差价与服务费。
一句话：咱们卖的不是"软件"，是"可靠、便宜、可计费的 Claude 调用能力"。
本模块术语：上游(key/base)、中游(网关)、下游(客户)、计费、token。

2. 上下游架构

上游（Claude 端点，key+base_url）
        │
        ▼
中游（sub2api / newapi / oneapi 网关）
        │  鉴权 / 转发 / 计费 / 限流 / 多上游负载均衡
        ▼
下游（客户：Claude Code、API 调用、代理）

讲师现场在白板上画，学员照着画。
强调：中游是公司核心资产——上游会变、客户会变，但"把上游能力变成可计费服务"的能力才是壁垒。

3. sub2api / newapi / oneapi 角色

组件	角色	说明
sub2api	公司自研计费系统（主营业务核心）	面向客户的订阅、Token 计费、余额、流水
newapi	通用 LLM API 网关（开源部署）	渠道、令牌、分组、定价，统一 OpenAI 兼容接口
oneapi	newapi 前身/同类	同 newapi 的定位，公司历史版本

记忆法：newapi 类负责"把上游变成统一 API"，sub2api 负责"面向客户算钱"。
本期培训第 3 周（D13-D15）会深挖这两块。

4. 公司服务清单与域名体系

域名体系：*.akria.net（如 api.akria.net、oneapi.akria.net、db.akria.net、kuma.akria.net）。
集群：prod k3s（唯一生产集群），另有 dev 办公内网集群。
常见服务（详见 CLAUDE.md 服务索引）：
- api.akria.net → core-api-v2（Python FastAPI）
- oneapi.akria.net → newapi（LLM 网关）
- db.akria.net → nocodb（低代码数据库后台）
- kuma.akria.net → uptime-kuma（服务监控）
- monitor.akria.net → headlamp（K8s 控制台）
部署方式：GitHub Actions + git tag 触发 → 构建镜像 → 推到 registry → k3s 拉取部署（D6/D22 细讲）。
镜像仓库：registry.akria.net。

5. 业务数据流：一次客户请求全流程（本模块最关键）

客户用自己申请的 API key 请求网关（如 newapi 的 /v1/chat/completions）。
网关鉴权：校验 key 是否有效、属于谁、有没有被禁用。
网关检查余额：账户有没有钱。
网关按策略选一个上游端点，转发请求。
上游 Claude 处理，流式返回 token。
网关统计本次用了多少输入/输出 token，调计费扣款、记流水。
结果返回给客户。

作业（D1）要求学员把这条链画出来。
讲师强调："第 6 步计费"是最容易被忽略但最核心的一步，D15 会专门展开。

6. 开发环境搭建（讲师演示 + 学员实操）

SSH key：ssh-keygen -t ed25519 -C "你的名字@akria.net"，公钥交给负责人加白。
工具链：git、python3、node、docker、kubectl、编辑器（VSCode）。
克隆仓库：git clone git@github.com:ChangUoo-insight/insightful-ops.git
kubectl 切换集群：公司脚本 kuse prod / kuse dev（D8 细讲，今天只要装好）。
测试环境说明：公司有测试集群；生产集群（prod）只读。

7. 公司规范（今天起就生效）

与 AI 协作、写代码、提交信息一律中文。
操作分级：
- Class A（需批准）：kubectl apply/patch/delete、git push、mv/rm 覆盖、数据库写操作、Secret 改动……
- Class B（可直接执行）：编辑 md/yaml/json 配置、创建源文件、创建未应用的清单。
有运维价值的操作要记入 OPS_JOURNAL.md。
新人红线：生产集群只读；任何写操作先问。

讲解节奏建议（约 90 分钟）

时段	内容
09:00-09:20	开场 + 业务模型（token 是什么、怎么赚钱）
09:20-09:50	上下游架构 + 三个网关角色（白板画图）
09:50-10:10	服务清单与域名体系（打开 CLAUDE.md 对照）
10:10-10:30	一次请求全流程（反复讲，学员复述）
10:30-11:10	环境搭建讲师演示（每步让学员跟做）
11:10-11:30	公司规范 + 新人红线
11:30-12:00	学员开始作业（画图 + 环境验证）

常见误区汇总

误区	正确理解
网关就是"转发一下"	网关核心是鉴权 + 计费 + 限流 + 多上游管理，转发只是表象
公司卖的是 key	卖的是通过统一网关交付、可计费的 token 使用能力，计费是壁垒
生产集群可以随便操作	新人只读，任何写操作先批准，违反是红线
有 key 就能直接卖给客户	必须经过网关：否则无法鉴权、无法计费、无法限流
计费是小事，后面再说	计费是主营业务核心，D15 专门展开，从今天就要有这个意识

D1 业务全景与开发环境

On this page