Documentation Index
Fetch the complete documentation index at: https://tech.illasoft.com/llms.txt
Use this file to discover all available pages before exploring further.
kira-inngest 是自托管的开源 Inngest 服务器，承担 Kira 整个异步任务编排。kira-be 向它发事件，kira-video-worker / kira-music-worker 注册为 Inngest function 消费事件。2026-04-02 全量替代了原来的 NATS JetStream（kira-be commit 45d54f5）。
部署形态
| 项 | 值 |
|---|
| 镜像 | inngest/inngest:v1.17.9 |
| 平台 | Fly.io（sjc 单机） |
| 资源 | 1 CPU shared · 1 GB RAM |
| 端口 | 8288（内网 only） |
| 内网 URL | kira-inngest.internal:8288 |
| 启动命令 | inngest start --host 0.0.0.0 --port 8288 |
环境变量（Fly secrets）
INNGEST_EVENT_KEY # 客户端发事件的鉴权 key
INNGEST_SIGNING_KEY # 请求签名
INNGEST_POSTGRES_URI # 持久化（事件/步骤存储）
INNGEST_REDIS_URI # 执行队列
事件命名规范
事件按 {domain}/{action}-{provider}.requested 格式命名，由 kira-be/src/lib/tasks.ts 派发。
Video domain
| toolName : provider | Event |
|---|
generateVideo:seedance | video/generation-seedance.requested |
generateVideo:grok | video/generation-grok.requested |
motionControl | video/motion-control-tencentcloud-vod-kling.requested |
videoEdit:ws-wan27 | video/edit-ws-wan27.requested |
videoEdit:kie-seedance2 | video/edit-kie-seedance2.requested |
videoExtend:ws-wan27 | video/extend-ws-wan27.requested |
upload | video/upload-kira.requested |
trimVideo | video/trim-kira.requested |
| Cancel broadcast | video/task.cancelled |
Music domain
| toolName | Event |
|---|
generateMusic | music/generation-kie-suno.requested |
generateInstrumental | music/instrumental-kie-suno.requested |
addVocals | music/add-vocals-kie-suno.requested |
upload | music/upload-kira.requested |
trimAudio | music/trim-kira.requested |
| Cancel broadcast | music/task.cancelled |
Event payload
{
taskId: string,
userId: string,
threadId: string,
toolName: string,
provider: string,
input: Record<string, unknown>,
priority: number
}
Priority Queue
priority 由用户付费计划决定（kira-be/src/lib/tasks.ts:18-20）：
| plan | priority |
|---|
pro / pro_year / max / max_year | 100 |
free / basic / basic_year | 0 |
重试和超时
| 项 | 值 |
|---|
| 默认 retry | 2 |
| 单步超时 | 60 min |
| 并发控制 | per-user-per-tool = 1（同用户同工具串行） |
| Provider 级并发 | 50-100（按 provider 容量设定） |
取消机制（双通道）
kira-be (rewind / stop)
├─ inngest.send({ name: "video/task.cancelled", data: { taskId } }) ← 广播取消
└─ redis.set("cancel:{taskId}", "1", "EX", 3600) ← 标志位
↓
Worker step.run(...) 每个 step 开头
├─ 检查 Redis cancel key
└─ 命中则 throw NonRetriableError → Inngest 触发 cleanup function
- Redis TTL：3600 秒，足以覆盖最长 60 min 任务
- Cleanup function：退款（非 upload/trim 类）+ 通知用户
failed / cancelled
端到端数据流
kira-be kira-inngest worker
│ │ │
│ inngest.send(event) │ │
├────────────────────────────────>│ │
│ │ persist to Postgres │
│ │ queue in Redis │
│ │ (按 priority 排序) │
│ │ │
│ │ HTTP POST /api/inngest │
│ ├───────────────────────────>│
│ │ │
│ │ │ step.run("check")
│ │ │ step.run("notify-processing")
│ │ │ step.run("create-task")
│ │ │ step.run("poll-result")
│ │ │ step.run("post-process")
│ │ │ step.run("finalize")
│ │ │
│ │<───────────────────────────┤
│ │ ack / retry / fail │
step.run() 的输出被 Inngest 缓存到 Postgres；若 step 失败，Inngest 只重试失败步骤，不从头跑。
Dashboard
通过 WireGuard 连入内网后访问 http://kira-inngest.internal:8288，可看到：
- Events：已发送的事件、payload、时间戳
- Functions：注册的所有 function、运行历史、耗时分布
- Runs：单次 run 的 step 级追踪
- Queues：当前挂起/运行中的任务数
本地开发
# 在任意 worker repo
INNGEST_DEV=1 bun run dev
# 或启动本地 Inngest dev server
npx inngest-cli dev
kira-inngest。
与其他服务的关系
| 服务 | 角色 |
|---|
kira-be | Event producer；使用 @inngest/bun client |
kira-video-worker | Function consumer（7 个 function） |
kira-music-worker | Function consumer（4 个 function） |
kira-dragonfly | Priority queue 存储 + cancel flag |
Supabase Postgres | Inngest 事件/step 持久化 |
Caveat
- Inngest Cloud 和 self-hosted 的 SDK 相同；切回 Cloud 只需改 env
- Postgres 和 Redis 必须稳定；任一宕机会导致整个任务系统失效
- 单机部署，暂无高可用；v1.17.9 的 Inngest 支持集群，有需要时升级
