人工智能AI Agent网络安全后端前端【免费下载链接】AiSOCOpen-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATTCK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.项目地址https://gitcode.com/GitHub_Trending/ai/AiSOC点击查看免费下载本文以 AiSOC 官方运维文档《Upgrades and versioning》为骨架结合仓库中的迁移执行器、CLI 实现与 Helm/Compose 配置完整讲清 AiSOC 的版本号含义、破坏性变更判定、弃用窗口、升级前检查清单、就地升级命令序列、升级验证、回滚边界以及跨大版本演进时运维必须做的事。读完你可以独立规划并执行一次可回滚、可验证的 AiSOC 升级。一、单一版本号贯穿整个 monorepoAiSOC 在 monorepo 内采用统一版本号遵循 Semantic Versioning所有发布 tag、容器镜像与 SDK 包都打同一个号。需要特别说明的是文档中的示例命令以v7.3.1为参照而当前仓库VERSION文件的实际内容是20.1.0。变量含义不变但你在执行git checkout时必须以目标 release 的真实 tag 为准不要照抄示例里的7.3.1cat VERSION # 当前工作树的版本号 git fetch --tags git tag --sort-v:refname | head -20 # 确认目标 tag 真实存在版本号的三个数字在 AiSOC 中承载的是契约强度而不仅仅是数字游戏位含义契约Patchx.y.Z缺陷修复、安全补丁、文档修正永远向后兼容Minorx.Y.0新连接器、新 Agent、新端点向后兼容现有配置无需改动MajorX.0.0累积的破坏性变更可能需要停机迁移、删除端点、重命名环境变量每次发布都带有 CHANGELOG.md 条目列出新增功能、行为变更与破坏性说明。跨大版本升级前必须先读 CHANGELOG这是文档里唯一加粗强调的操作纪律。发布节奏通道频率内容Patchx.y.Z按需通常每周Bug 修复、安全补丁、文档修复始终向后兼容Minorx.Y.0约 1–3 周一次新连接器、新 Agent、新端点向后兼容现有配置继续可用MajorX.0.0破坏性变更累积到一定程度时需要停机的 schema 迁移、移除的端点、重命名的环境变量二、AiSOC 如何判定“破坏性变更”一个变更只要满足以下任意一条就算破坏性变更必须进 major 版本现有 REST/GraphQL/WebSocket 端点的请求或响应结构发生非增量式变化环境变量被重命名或其解析语义发生变化数据库迁移无法在不丢数据的前提下回滚连接器 schema 变化导致此前合法的auth_configJSON 会被拒绝内置角色的权限列表被缩减增加权限不算破坏性SDK 函数签名发生非增量式变化。反过来新增端点、新增字段、新增连接器、新增权限、新增可选环境变量都属于非破坏性变更走 minor 发布。这条规则对运维的直接价值是minor 升级通常不需要改动你的配置文件和调用方代码需要改的是 major。这一判定与仓库中的实际做法一致。例如v13→v14之后platform_admin与admin无法再通过任何 API 路由授予详见下方跨大版本表格这正是“权限模型收紧”被放进 major 而不是 patch 的原因。三、弃用政策三段式退场AiSOC 对准备移除或改变的行为执行固定三段式流程在 minor 发布中宣告弃用。CHANGELOG 点名弃用项运行时会输出警告日志OpenAPI spec 把该端点标记为deprecated: true。至少保持一整个大版本周期可用。如果在6.3.0弃用某行为下一个 major 是7.0.0那么该行为在全部6.x中仍然工作。在 major 发布中移除。CHANGELOG 的 “Breaking” 段落明确写出移除项并给出替代方案链接。如果你依赖了被标记为 deprecated 的能力官方建议开 issue —— 有时窗口会被延长。对运维的实务含义是看到弃用警告不要当成噪音把它排进下一个 major 的改造计划否则你会在跨版本时被动挨打。四、升级前的五项检查清单每次都要做文档要求每次升级都完整走一遍读 CHANGELOG范围覆盖当前版本到目标版本之间。重点关注标注 “Breaking”、“Migration”、“Action required” 的条目。备份数据库。pg_dumpAiSOC schema 是最低要求使用 Kafka、ClickHouse 的部署也要一并快照。单独备份AISOC_CREDENTIAL_KEY。升级过程中丢失该密钥数据库里所有加密的连接器凭据将永久不可恢复。请像对待数据库备份一样对待它。为 API 服务确认维护窗口。迁移尽可能在单个事务内执行minor 通常几秒major 在大表audit_log上可能耗时数分钟。先升级预发布环境。如果你有一个与生产同代码的非生产租户先升级它并观察一天再推进生产。第 3 条容易被忽略但它比 schema 更致命schema 坏了可以还原快照凭据密钥丢了则没有任何还原路径——加密数据本身还在解密能力消失了。五、就地升级stop → pull → migrate → start官方支持的升级路径是“停、拉、迁、启”。同一 minor 内的多副本滚动升级是安全的跨 major 的滚动升级不支持因为仍在运行的旧代码可能无法理解已被迁移的 schema。# 1. 在入口层把新流量挡掉对 API 服务返回 503。 # 2. 停掉 API 服务副本。连接器与 ingest 可以继续运行 —— # 它们能容忍 API 短暂不可用并把反压写回 Kafka。 cd /opt/aisoc # 你的安装路径 git fetch --tags git checkout v7.3.1 # 目标 tag请替换为你实际要升到的版本 # 3. 拉取依赖 pnpm install --frozen-lockfile (cd services/api uv sync) # 4. 执行数据库迁移 # v7.3.1 起可直接用 CLI aisoc db upgrade # 等价于cd services/api uv run python -m app.scripts.run_migrations # 设置 AISOC_MIGRATIONS_STRICT1让失败的迁移中断流程。 # 不设置时runner 只记录失败、回滚该条语句、继续执行并最终 exit 0 —— # 等于静默交付一个只应用了一半的 schema。 # 5. 重新启动 API 服务 docker compose -f docker-compose.yml -f infra/compose/docker-compose.dev.yml up -d api # 6. 验证健康状态并摘除维护开关 curl -fsS http://localhost:8000/healthz5.1AISOC_MIGRATIONS_STRICT到底改变了什么这条建议不是“最佳实践口号”而是源码里的真实分支。在 迁移执行器 中每个迁移文件的失败都会被收集然后if failures: logger.warning(%d migrations failed; see logs above, len(failures)) if os.environ.get(AISOC_MIGRATIONS_STRICT, ).strip().lower() in {1, true, yes, on}: raise SystemExit(f{len(failures)} migration(s) failed in strict mode)也就是说AISOC_MIGRATIONS_STRICT接受1 / true / yes / on四种写法。不设置时循环跑完、进程以 0 退出CI 或发布流水线会以为一切正常设置后才会以非零状态中断。生产升级务必显式设置为 1。5.2 另一个容易被忽略的开关AISOC_MIGRATIONS_REQUIRED除文档提到的STRICT外执行器还提供AISOC_MIGRATIONS_REQUIRED默认1用来控制连接失败是否致命raw os.environ.get(AISOC_MIGRATIONS_REQUIRED, 1).strip().lower() return raw not in {0, false, no, off}默认1连不上 Postgres 就直接抛错部署失败。这是生产应有的行为——“代码不能带着过期 schema 上线”。设为0仅在 demo 类环境使用。连接重试耗尽后输出醒目的MIGRATION SKIPPED日志并以 0 退出让代码部署继续但连接建立后出现的 SQL 错误依然致命。执行器还内置了约 3 分钟的连接重试窗口10 次指数退避上限 12 秒专门应对托管 Postgres 冷启动、故障切换这类瞬时不可达for attempt in range(1, 11): try: return await asyncpg.connect(dsn, timeout10, **kwargs) except ( asyncpg.exceptions.ConnectionDoesNotExistError, asyncpg.exceptions.CannotConnectNowError, ConnectionResetError, OSError, ) as exc: ... delay min(2 ** (attempt - 1), 12)认证类错误如InvalidPasswordError被刻意排除在重试之外——那需要人来看重试无意义。5.3aisoc db upgrade的实际行为CLI 的db upgrade子命令并不是在本地直连数据库而是委托给正在运行的 compose 栈见 CLI 入口cmd [ docker, compose, *_compose_file_arg(repo_root), exec, -T, service, python, -m, app.scripts.run_migrations, ]这带来两个实操结论栈必须先起来。命令失败时 CLI 会提示If the stack is not up yet, run aisoc serve first, then re-run this command.对应测试 也断言了这条输出。所以文档流程里“先停 API 再 migrate”需要按你的部署形态调整要么保留 API 容器但把入口流量摘掉推荐这样db upgrade可用要么用uv run python -m app.scripts.run_migrations在宿主机直接执行。--service参数可换。默认api如果你的迁移职责落在别的服务容器上可以显式指定。5.4 迁移是怎么被“记住”的执行器在目标库中维护一张记账表避免重复应用CREATE TABLE IF NOT EXISTS aisoc_schema_migrations ( name TEXT PRIMARY KEY, applied_at TIMESTAMPTZ NOT NULL DEFAULT now() );每个成功应用的迁移会写入name即文件名如042_alerts_schema_drift_fix.sql下次运行只处理pending未记录的文件并按文件名排序执行。这也解释了为什么迁移文件的命名顺序即是执行顺序以及为什么当前仓库里存在042_alerts_schema_drift_fix.sql与042_waitlist.sql、三个096_*这类同号文件——排序在同号内按文件名字典序决定。5.5 为什么不用 Alembic多语句 SQL 与连接污染services/api的迁移器是自研的、前向-only的纯 SQL 执行器原因写在文件头的注释里非常值得运维理解迁移文件常包含多语句脚本BEGIN; … COMMIT;、多个CREATE TABLE。SQLAlchemy asyncpg 会走 asyncpg 的预备语句协议直接抛cannot insert multiple commands into a prepared statement。曾经的做法是在engine.begin()里取出底层 asyncpg 连接来执行虽然解决了多语句问题但把裸Connection.execute()与 SQLAlchemy 的事务管理混用导致连接池里的连接被“污染”后续请求报cannot use Connection.transaction() in a manually started transaction。现在每条迁移使用一条独立的、短命的 asyncpg 连接关闭后才开始对外服务两个问题同时消失。此外执行器还会把 SQLAlchemy 风格的 DSN 归一化给 asyncpg去掉asyncpg后缀把sslmode转成 asyncpg 的ssl参数丢弃channel_binding所以你可以直接用应用侧那套DATABASE_URL字符串。5.6 迁移连接的是“属主角色”不是运行时角色这是 v10 之后的关键点。DATABASE_URL指向aisoc_app——它只有SELECT/INSERT/UPDATE/DELETE这样行级安全策略才对它生效见 061_runtime_app_role.sql。但 DDL 需要表属主权限因此执行器优先读DATABASE_MIGRATION_URLdef migration_url() - str: configured (settings.DATABASE_MIGRATION_URL or ).strip() return configured or str(settings.DATABASE_URL)未配置时回退到DATABASE_URL这是单角色部署的合理默认。日志会打印实际使用的角色与来源升级时请留意这一行Found N migration files; connecting as role (DATABASE_MIGRATION_URL)如果AISOC_APP_DB_PASSWORD已设置执行器还会在迁移链跑完后顺手把运行时角色的登录口令落到aisoc_app上通过set_config传入不拼接进 SQL。原因是 compose 的 initdb 钩子只在空数据目录时触发就地升级永远走不到它。未设置该变量属于正常状态只记一条 info 日志。5.7 Fly.io 与 Kubernetes 的差异Fly 部署把迁移挂在release_command上见 infra/fly/api/fly.toml先删除哨兵文件再跑迁移成功写出/tmp/aisoc-migrations-ok后才执行seed_demo。软失败数据库不可达时哨兵不写seed 也被跳过——避免 seed 撞上同一个连接错误再崩一次。Kubernetes 的流程同构把 API Deployment 缩到 0用Job跑迁移再扩回来。需要注意文档提到 Helm chart 通过helm upgrade --set runMigrationstrue暴露该能力但在当前离线仓库的 infra/helm/aisoc 模板与 values.yaml 中未检索到runMigrations这个键。因此请以“缩容 Job 扩容”为准并在使用 chart 前用helm show values核对目标 chart 版本是否提供该开关。chart 里确实提供的相关配置是database-migration-url属主 DSN只给迁移用以及AISOC_APP_DB_PASSWORD的三步落地说明。六、v7.3.1 的迁移幂等性历史案例方法论通用文档用一个 :::tip 记录了 v7.3.1 的修复靠近 7.x 的三个迁移——005_compliance.sql、025_connectors_click_and_connect.sql与新增的042_alerts_schema_drift_fix.sql——被改成幂等。若此前升级把alerts表迁到一半直接重跑aisoc db upgrade即可。仓库中的 042_alerts_schema_drift_fix.sql 完整展示了这种写法它把 ORM 模型里声明却从未进 schema 的列补齐BEGIN; -- 实体反范式化 ALTER TABLE alerts ADD COLUMN IF NOT EXISTS affected_ips JSONB NOT NULL DEFAULT []::jsonb; ALTER TABLE alerts ADD COLUMN IF NOT EXISTS affected_hosts JSONB NOT NULL DEFAULT []::jsonb; ALTER TABLE alerts ADD COLUMN IF NOT EXISTS affected_users JSONB NOT NULL DEFAULT []::jsonb; ALTER TABLE alerts ADD COLUMN IF NOT EXISTS affected_assets JSONB NOT NULL DEFAULT []::jsonb; -- 合并 / 父子关系 ALTER TABLE alerts ADD COLUMN IF NOT EXISTS parent_alert_id UUID; ALTER TABLE alerts ADD COLUMN IF NOT EXISTS child_alert_ids JSONB NOT NULL DEFAULT []::jsonb; ALTER TABLE alerts ADD COLUMN IF NOT EXISTS is_merged BOOLEAN NOT NULL DEFAULT FALSE; -- 分派 ALTER TABLE alerts ADD COLUMN IF NOT EXISTS assigned_to_id UUID; ALTER TABLE alerts ADD COLUMN IF NOT EXISTS assigned_at TIMESTAMPTZ; -- 富化 / 标签 ALTER TABLE alerts ADD COLUMN IF NOT EXISTS enrichment_data JSONB NOT NULL DEFAULT {}::jsonb; ALTER TABLE alerts ADD COLUMN IF NOT EXISTS tags JSONB NOT NULL DEFAULT []::jsonb; COMMIT;该文件头注释记录了这个问题的真实症状全新aisoc serveaisoc db upgrade能顺利起栈但GET /api/v1/alerts返回 500因为 asyncpg 找不到alerts.affected_ips、alerts.tags等列。这正是“幂等 只加缺失列”这条设计纪律的由来在公开仓库里迁移应当可重复执行。七、升级后的验证四件事升级成功后以下四项都应通过# 1. 健康与就绪 curl -fsS http://localhost:8000/healthz curl -fsS http://localhost:8000/readyz # 200 且 body 中没有 degraded 服务 # 2. 基准对比 aisoc-cli benchmark # 或 pnpm aisoc:benchmark数值应持平或更好 # 3. 分析师控制台底部显示的版本号与新 tag 一致 # 4. 版本接口返回同一个号 curl -fsS http://localhost:8000/api/v1/system/version/readyz在源码中是一个“阶段化”的就绪探针进程起来即/livez返回 200而/readyz在 lifespan 管理的组件全部完成前返回 503services/api/app/main.py 中对此有明确注释Phase 2.6。所以readyz一直 503 通常意味着某个依赖组件卡住了而不是迁移本身失败。任何一项失败转到 Troubleshooting。八、回滚代码可退schema 不可退这是整篇文档最需要读懂的一段也是最容易踩坑的地方。services/api使用前向-only的 SQL 迁移执行器 services/api/app/scripts/run_migrations.py不是 Alembic没有alembic.ini没有alembic/目录没有 downgrade 概念。全仓只有四个服务使用 Alembic——ueba、honeytokens、purple-team、osquery-tls。这一点可以直接用目录结构验证services/ueba/alembic/ services/honeytokens/alembic/ services/purple-team/alembic/ services/osquery-tls/alembic.ini结论回退代码到上一个 tag 是支持的回退 schema不支持。真正需要旧 schema 的“回滚”等价于恢复升级前清单第 2 步的数据库快照。Patch 与 minor 设计上可干净回滚流程与升级镜像对称git checkout v7.3.0 # 上一个 tag pnpm install --frozen-lockfile (cd services/api uv sync) # 没有 schema downgrade 步骤API 的迁移执行器是前向-only 的。 # 增量式迁移常见情况向后兼容因此旧代码可以跑在新 schema 上。 # 如果某次迁移是破坏性的请改为恢复快照 —— CHANGELOG 会把它标记为不可逆。 docker compose -f docker-compose.yml -f infra/compose/docker-compose.dev.yml up -d api逻辑很清晰绝大多数迁移只是加列、加表、加索引旧代码不读这些新结构所以“旧代码 新 schema”能跑。一旦某个 major 带来单向迁移例如删除列CHANGELOG 会标注 “irreversible”此时唯一回滚路径就是快照。九、跨大版本升级运维必须逐条对照的动作表每跨一个 major 都要读对应那一行。破坏性清单的权威来源是 CHANGELOG 的### BREAKING段下表回答的是“运维要做什么”。从 → 到变化你要做的事any →v10.0.0服务不再以超级用户连接 Postgres92 条行级安全策略开始真正生效。四个自带 alembic 链的服务以属主身份、而非应用角色迁移。用DATABASE_MIGRATION_URL指向属主角色跑迁移。以超级用户连接的服务会绕过全部策略升级前后都要核对连接角色。v10 →v11.0.0POST /v1/ingest与/v1/ingest/batch要求凭据。CORE 需要8 GB 内存、20 GB 磁盘此前约 6.5 GB。升级前先签发 ingest token 并配置到所有生产者否则数据摄入直接停止。先确认宿主机资源余量。v11 →v12.0.0在必需 secret 未设置前actions 服务对所有变更类路由返回 503realtime 边缘拒绝所有连接。启动整套栈之前就把 secret 配好。这两处失败是刻意设计且非常显眼。v12 →v13.0.075 条状态变更路由开始要求此前不需要的权限其中若干条迁移到settings:write而soc_analyst、soc_lead、threat_hunter并未持有该权限。预期出现 HTTP 403——原本返回 200 的调用会失败。升级前就梳理谁需要settings:write。v13 →v14.0.0任何路由都不能授予超出调用者自身权限的角色、scope 或组织成员关系platform_admin与admin无法从任何 API 路由触达。唯一铸造通配角色的方式是针对数据库执行python -m app.scripts.bootstrap_admin。任何通过 API 创建通配角色的自动化都会失效。v14 →v15.0.0/api/v1/shifts被移除/api/v1/threatintel/stix/*的读取在 demo 模式外返回 404。make up启动的是生产级栈AISOC_DEV_MODE不再默认为开启。删除这些路由的调用方它们本来也不承载人工录入的数据。若你依赖开发态认证旁路需显式设置ENVIRONMENTdevelopment原先静默的告警会变成启动拒绝。v15.0.0 →v15.1.0不破坏兼容新增 2 条路由、未移除任何路由。但两处行为明显变化CloudTrail 部署会看到更多告警此前所有事件被折叠成一条告警触发的 playbook 现在真的会执行此前find_matching()没有生产调用方。升级本身无需动作。预期 CloudTrail 告警量回到应有水平升级前检查哪些 playbook 是启用的——从未触发过的 playbook 现在会触发默认以 preview 模式运行需要三项 opt-in 才会真正执行动作。v15.1.0 →v16.0.0cases表消失。迁移 083 把其行移入aisoc_cases重指子表外键并把旧表重命名为cases_pre_consolidation。两张表从未同步控制台写一张、所有 case 指标读另一张导致 MTTR 和 case 计数对分析师创建的每一个 case 都是盲的。另外 SAML/OIDC 登录开始工作——此前因连接表没有写入方而在所有部署上返回 403。检查你自己的 SQL。任何查询cases的东西Grafana 面板、定时导出、报表都必须改读aisoc_cases。它会以 “relation does not exist” 明确失败而不是返回过期数据这是刻意设计。需要对比时归档表可读。升级瞬间 case 指标会变化它们此前是少报而非多报。若使用 SSO先POST /api/v1/sso-connections建连接再放用户进来。v16.0.0 →v16.0.1不破坏兼容。安全发布修复高危提权GHSA-4gx4-x7gm-4xq8判断调用者能否授予权限的检查读的是静态角色而准入路由的检查读的是数据库解析后的权限。当租户用roles/user_roles收窄账号时两者答案不同被收窄的账号可以授予其未收窄角色所携带的任何权限。若你通过数据库 RBAC 限制账号必须升级。没有任何 RBAC 行的部署从未暴露——静态映射对它本就是正确答案。升级后超出调用者实际持有范围的授予会被拒绝因此此前依赖更宽静态角色派发角色的运维会拿到 403应通过 RBAC 授予其权限而不是放宽静态角色。v16.0.1 →v17.0.0移除三条路由POST /detection-loop/suggest与两条GET /detection-loop/suggestions读接口及其三个 schema。无需迁移因为它们从未真正可用——它们查询aisoc_alerts、aisoc_detection_rules与alerts.evidence而这些没有任何迁移创建。等价且受治理的接口是POST /api/v1/detection-proposals。有一个数字改了含义却不报错值得读两遍/api/v1/metrics/dashboard上的alerts.total现在统计未结工作new、triaging、in_progress而不是历史上收到的全部告警相邻的严重度计数同口径。用该字段画累计摄入量的面板会掉到你的队列大小。已结工作单独以alerts.resolved报告。迁移090给aisoc_cases加三个可空列属增量自动执行。删除调用方更新面板口径确认090已跑过。关于 v16 的cases合并源码里能读到完整的设计意图。083_one_case_table.sql 的注释直白写明控制台写aisoc_cases含六态状态机、sla_due_at、evidence_chain、observable_graph而所有指标读casesresolution_time、metrics、insights、executive_digest、mssp_portfolio、GraphQL 查询层于是“分析师创建的每个 case 对所有 case 指标都不可见”。迁移选择保留aisoc_cases并采用可判定的重命名而非 dropIF to_regclass(public.cases_pre_consolidation) IS NULL THEN ALTER TABLE cases RENAME TO cases_pre_consolidation; END IF;这段用to_regclass守卫使全新部署cases可能不存在成为 no-op 而不是报错。同时它还处理了状态词表差异cases.statusopen/resolved…与aisoc_casesnew/triaged/investigating/contained/resolved/closed不同采用映射而非照抄否则落到目标状态机之外的状态会让该 case 在控制台里无法流转。一次跨多个 major 是支持的但未作为单步测试过。请逐个升级、每次之间跑迁移这样出问题时能明确指出是哪个版本导致的。十、版本偏移Version skew的兼容边界在同一个 major 内下列组件在一个 minor 版本的偏移范围内保证线上兼容浏览器 ↔ API 服务API 服务 ↔ 连接器API 服务 ↔ AgentSDK 客户端Go、Python、TypeScript↔ API因此你完全可以把 API 升到6.1.0、连接器仍留在6.0.x花一天完成滚动而不破坏任何东西。跨 major6.x↔7.x契约重置先升 API再升其他组件且必须在同一个维护窗口内完成。这种“API 先行”的纪律与运行时角色分离、RLS 策略是同一套思路的两个侧面schema 是单一事实源API 是唯一懂它的读端其余组件必须跟着 API 的节奏走。十一、长期支持LTS现状AiSOC 目前不提供正式的 LTS 发布。最新 major 就是受支持版本安全补丁与 CVE 修复会在新 major 落地后回溯 90 天到上一个 major——这正是官方预期的运维规划与执行窗口。如果你的环境需要更长支持周期官方建议在 Discussions 中提出愿意讨论商业支持安排。请注意这是政策承诺不是代码行为因此无法在仓库里验证只能以文档为准。十二、Pre-1.0 历史与起点建议1.0.0到5.x是早期功能建设阶段发布的版本记录在 CHANGELOG.md。6.0.02026 年 5 月是第一个被认为可用于生产的版本新部署应从最新 tag 起步文档写作时为v7.3.1而当前工作树VERSION已到20.1.0。这段历史对升级决策的现实意义是1.x–5.x不承诺生产级兼容语义任何从这些版本出发的升级都应视为重建部署而非就地升级——先按目标版本部署一套干净环境再用数据导出/导入迁移业务数据比在旧 schema 上层层叠迁移安全得多。十三、一页速查升级执行清单[准备] □ 读 CHANGELOG当前 → 目标标出 Breaking / Migration / Action required □ pg_dump 备份Kafka / ClickHouse 一并快照 □ 备份 AISOC_CREDENTIAL_KEY丢失即凭据永久不可解 □ 确认维护窗口major 在 audit_log 大表上可能数分钟 □ 预发布租户先升级并观察 24 小时 [执行] □ 入口摘流503停 API 副本连接器 / ingest 可继续 □ git fetch --tags git checkout 目标 tag □ pnpm install --frozen-lockfile □ (cd services/api uv sync) □ 设置 DATABASE_MIGRATION_URL属主角色 DSNv10 □ 设置 AISOC_MIGRATIONS_STRICT1 □ aisoc db upgrade # 或 uv run python -m app.scripts.run_migrations □ docker compose ... up -d api [验证] □ /healthz 200 □ /readyz 200 且无 degraded □ aisoc-cli benchmark 数值持平或更好 □ 控制台页脚版本 /api/v1/system/version 新 tag [跨 major 追加] □ 逐个大版本推进每个之间跑一次迁移 □ 逐行对照“跨大版本动作表” □ 有 SSO 时先建 /api/v1/sso-connections □ 自定义 SQL / Grafana / 导出脚本改读 aisoc_casesv16 起 □ 面板口径确认 alerts.total 只算未结v17 起 [回滚] □ 代码可退回上一 tag前向-only无 schema downgrade □ 需要旧 schema ⇒ 只能恢复快照结语AiSOC 的升级模型可以用三句话概括版本号即契约单一VERSION贯穿 tag、镜像与 SDK迁移前向-only靠真实 SQL 幂等性 aisoc_schema_migrations记账表而不是 down 脚本回滚只退代码不退 schema需要旧结构就还原快照。把AISOC_MIGRATIONS_STRICT1、DATABASE_MIGRATION_URL指向属主角色、以及跨 major 的逐行动作表这三件事做对绝大多数升级事故都可以在发生前被消除。延伸阅读CHANGELOG.md破坏性变更权威清单、迁移执行器、CLI 入口、运行时角色迁移、case 表合并迁移、Fly 发布命令、Helm values。赞分享人工智能AI Agent网络安全后端前端【免费下载链接】AiSOCOpen-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATTCK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.项目地址https://gitcode.com/GitHub_Trending/ai/AiSOC点击查看免费下载相关推荐Service Weaver版本管理与升级如何平滑迁移到新版本Service Weaver版本管理与升级如何平滑迁移到新版本 Service Weaver是一个用于编写和部署云应用的编程框架其版本管理策略确保了应用程序后端微服务云原生RPC框架开发工具如何快速上手LitePCIe从安装LiteX环境到生成第一个PCIe核心的5步教程如何快速上手LitePCIe从安装LiteX环境到生成第一个PCIe核心的5步教程 LitePCIe 是一款由 EnjoyDigital 开发的小面积、可配置用 Dify 零代码搭建电商文案生成应用10 分钟从 0 到 1 跑通用 Dify 零代码搭建电商文案生成应用10 分钟从 0 到 1 跑通 运营同事刚把第 37 条商品标题改完。商品名、卖点、人群都填进表格文案却总差一口气。人工智能大模型AI 应用AI AgentRAG后端前端工作流自动化低代码上一篇掌握CANN ClipByValue算子从数据安全到性能优化的完整指南下一篇Noodle平台技术债务管理保持教育项目健康的长期策略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/11/4 1:33:31 · 阅读 1.2k AiSOC 升级与版本管理实战：从语义化版本、前向迁移到跨大版本平滑演进
人工智能AI Agent网络安全后端前端【免费下载链接】AiSOCOpen-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATTCK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.项目地址https://gitcode.com/GitHub_Trending/ai/AiSOC点击查看免费下载本文以 AiSOC 官方运维文档《Upgrades and versioning》为骨架结合仓库中的迁移执行器、CLI 实现与 Helm/Compose 配置完整讲清 AiSOC 的版本号含义、破坏性变更判定、弃用窗口、升级前检查清单、就地升级命令序列、升级验证、回滚边界以及跨大版本演进时运维必须做的事。读完你可以独立规划并执行一次可回滚、可验证的 AiSOC 升级。一、单一版本号贯穿整个 monorepoAiSOC 在 monorepo 内采用统一版本号遵循 Semantic Versioning所有发布 tag、容器镜像与 SDK 包都打同一个号。需要特别说明的是文档中的示例命令以v7.3.1为参照而当前仓库VERSION文件的实际内容是20.1.0。变量含义不变但你在执行git checkout时必须以目标 release 的真实 tag 为准不要照抄示例里的7.3.1cat VERSION # 当前工作树的版本号 git fetch --tags git tag --sort-v:refname | head -20 # 确认目标 tag 真实存在版本号的三个数字在 AiSOC 中承载的是契约强度而不仅仅是数字游戏位含义契约Patchx.y.Z缺陷修复、安全补丁、文档修正永远向后兼容Minorx.Y.0新连接器、新 Agent、新端点向后兼容现有配置无需改动MajorX.0.0累积的破坏性变更可能需要停机迁移、删除端点、重命名环境变量每次发布都带有 CHANGELOG.md 条目列出新增功能、行为变更与破坏性说明。跨大版本升级前必须先读 CHANGELOG这是文档里唯一加粗强调的操作纪律。发布节奏通道频率内容Patchx.y.Z按需通常每周Bug 修复、安全补丁、文档修复始终向后兼容Minorx.Y.0约 1–3 周一次新连接器、新 Agent、新端点向后兼容现有配置继续可用MajorX.0.0破坏性变更累积到一定程度时需要停机的 schema 迁移、移除的端点、重命名的环境变量二、AiSOC 如何判定“破坏性变更”一个变更只要满足以下任意一条就算破坏性变更必须进 major 版本现有 REST/GraphQL/WebSocket 端点的请求或响应结构发生非增量式变化环境变量被重命名或其解析语义发生变化数据库迁移无法在不丢数据的前提下回滚连接器 schema 变化导致此前合法的auth_configJSON 会被拒绝内置角色的权限列表被缩减增加权限不算破坏性SDK 函数签名发生非增量式变化。反过来新增端点、新增字段、新增连接器、新增权限、新增可选环境变量都属于非破坏性变更走 minor 发布。这条规则对运维的直接价值是minor 升级通常不需要改动你的配置文件和调用方代码需要改的是 major。这一判定与仓库中的实际做法一致。例如v13→v14之后platform_admin与admin无法再通过任何 API 路由授予详见下方跨大版本表格这正是“权限模型收紧”被放进 major 而不是 patch 的原因。三、弃用政策三段式退场AiSOC 对准备移除或改变的行为执行固定三段式流程在 minor 发布中宣告弃用。CHANGELOG 点名弃用项运行时会输出警告日志OpenAPI spec 把该端点标记为deprecated: true。至少保持一整个大版本周期可用。如果在6.3.0弃用某行为下一个 major 是7.0.0那么该行为在全部6.x中仍然工作。在 major 发布中移除。CHANGELOG 的 “Breaking” 段落明确写出移除项并给出替代方案链接。如果你依赖了被标记为 deprecated 的能力官方建议开 issue —— 有时窗口会被延长。对运维的实务含义是看到弃用警告不要当成噪音把它排进下一个 major 的改造计划否则你会在跨版本时被动挨打。四、升级前的五项检查清单每次都要做文档要求每次升级都完整走一遍读 CHANGELOG范围覆盖当前版本到目标版本之间。重点关注标注 “Breaking”、“Migration”、“Action required” 的条目。备份数据库。pg_dumpAiSOC schema 是最低要求使用 Kafka、ClickHouse 的部署也要一并快照。单独备份AISOC_CREDENTIAL_KEY。升级过程中丢失该密钥数据库里所有加密的连接器凭据将永久不可恢复。请像对待数据库备份一样对待它。为 API 服务确认维护窗口。迁移尽可能在单个事务内执行minor 通常几秒major 在大表audit_log上可能耗时数分钟。先升级预发布环境。如果你有一个与生产同代码的非生产租户先升级它并观察一天再推进生产。第 3 条容易被忽略但它比 schema 更致命schema 坏了可以还原快照凭据密钥丢了则没有任何还原路径——加密数据本身还在解密能力消失了。五、就地升级stop → pull → migrate → start官方支持的升级路径是“停、拉、迁、启”。同一 minor 内的多副本滚动升级是安全的跨 major 的滚动升级不支持因为仍在运行的旧代码可能无法理解已被迁移的 schema。# 1. 在入口层把新流量挡掉对 API 服务返回 503。 # 2. 停掉 API 服务副本。连接器与 ingest 可以继续运行 —— # 它们能容忍 API 短暂不可用并把反压写回 Kafka。 cd /opt/aisoc # 你的安装路径 git fetch --tags git checkout v7.3.1 # 目标 tag请替换为你实际要升到的版本 # 3. 拉取依赖 pnpm install --frozen-lockfile (cd services/api uv sync) # 4. 执行数据库迁移 # v7.3.1 起可直接用 CLI aisoc db upgrade # 等价于cd services/api uv run python -m app.scripts.run_migrations # 设置 AISOC_MIGRATIONS_STRICT1让失败的迁移中断流程。 # 不设置时runner 只记录失败、回滚该条语句、继续执行并最终 exit 0 —— # 等于静默交付一个只应用了一半的 schema。 # 5. 重新启动 API 服务 docker compose -f docker-compose.yml -f infra/compose/docker-compose.dev.yml up -d api # 6. 验证健康状态并摘除维护开关 curl -fsS http://localhost:8000/healthz5.1AISOC_MIGRATIONS_STRICT到底改变了什么这条建议不是“最佳实践口号”而是源码里的真实分支。在 迁移执行器 中每个迁移文件的失败都会被收集然后if failures: logger.warning(%d migrations failed; see logs above, len(failures)) if os.environ.get(AISOC_MIGRATIONS_STRICT, ).strip().lower() in {1, true, yes, on}: raise SystemExit(f{len(failures)} migration(s) failed in strict mode)也就是说AISOC_MIGRATIONS_STRICT接受1 / true / yes / on四种写法。不设置时循环跑完、进程以 0 退出CI 或发布流水线会以为一切正常设置后才会以非零状态中断。生产升级务必显式设置为 1。5.2 另一个容易被忽略的开关AISOC_MIGRATIONS_REQUIRED除文档提到的STRICT外执行器还提供AISOC_MIGRATIONS_REQUIRED默认1用来控制连接失败是否致命raw os.environ.get(AISOC_MIGRATIONS_REQUIRED, 1).strip().lower() return raw not in {0, false, no, off}默认1连不上 Postgres 就直接抛错部署失败。这是生产应有的行为——“代码不能带着过期 schema 上线”。设为0仅在 demo 类环境使用。连接重试耗尽后输出醒目的MIGRATION SKIPPED日志并以 0 退出让代码部署继续但连接建立后出现的 SQL 错误依然致命。执行器还内置了约 3 分钟的连接重试窗口10 次指数退避上限 12 秒专门应对托管 Postgres 冷启动、故障切换这类瞬时不可达for attempt in range(1, 11): try: return await asyncpg.connect(dsn, timeout10, **kwargs) except ( asyncpg.exceptions.ConnectionDoesNotExistError, asyncpg.exceptions.CannotConnectNowError, ConnectionResetError, OSError, ) as exc: ... delay min(2 ** (attempt - 1), 12)认证类错误如InvalidPasswordError被刻意排除在重试之外——那需要人来看重试无意义。5.3aisoc db upgrade的实际行为CLI 的db upgrade子命令并不是在本地直连数据库而是委托给正在运行的 compose 栈见 CLI 入口cmd [ docker, compose, *_compose_file_arg(repo_root), exec, -T, service, python, -m, app.scripts.run_migrations, ]这带来两个实操结论栈必须先起来。命令失败时 CLI 会提示If the stack is not up yet, run aisoc serve first, then re-run this command.对应测试 也断言了这条输出。所以文档流程里“先停 API 再 migrate”需要按你的部署形态调整要么保留 API 容器但把入口流量摘掉推荐这样db upgrade可用要么用uv run python -m app.scripts.run_migrations在宿主机直接执行。--service参数可换。默认api如果你的迁移职责落在别的服务容器上可以显式指定。5.4 迁移是怎么被“记住”的执行器在目标库中维护一张记账表避免重复应用CREATE TABLE IF NOT EXISTS aisoc_schema_migrations ( name TEXT PRIMARY KEY, applied_at TIMESTAMPTZ NOT NULL DEFAULT now() );每个成功应用的迁移会写入name即文件名如042_alerts_schema_drift_fix.sql下次运行只处理pending未记录的文件并按文件名排序执行。这也解释了为什么迁移文件的命名顺序即是执行顺序以及为什么当前仓库里存在042_alerts_schema_drift_fix.sql与042_waitlist.sql、三个096_*这类同号文件——排序在同号内按文件名字典序决定。5.5 为什么不用 Alembic多语句 SQL 与连接污染services/api的迁移器是自研的、前向-only的纯 SQL 执行器原因写在文件头的注释里非常值得运维理解迁移文件常包含多语句脚本BEGIN; … COMMIT;、多个CREATE TABLE。SQLAlchemy asyncpg 会走 asyncpg 的预备语句协议直接抛cannot insert multiple commands into a prepared statement。曾经的做法是在engine.begin()里取出底层 asyncpg 连接来执行虽然解决了多语句问题但把裸Connection.execute()与 SQLAlchemy 的事务管理混用导致连接池里的连接被“污染”后续请求报cannot use Connection.transaction() in a manually started transaction。现在每条迁移使用一条独立的、短命的 asyncpg 连接关闭后才开始对外服务两个问题同时消失。此外执行器还会把 SQLAlchemy 风格的 DSN 归一化给 asyncpg去掉asyncpg后缀把sslmode转成 asyncpg 的ssl参数丢弃channel_binding所以你可以直接用应用侧那套DATABASE_URL字符串。5.6 迁移连接的是“属主角色”不是运行时角色这是 v10 之后的关键点。DATABASE_URL指向aisoc_app——它只有SELECT/INSERT/UPDATE/DELETE这样行级安全策略才对它生效见 061_runtime_app_role.sql。但 DDL 需要表属主权限因此执行器优先读DATABASE_MIGRATION_URLdef migration_url() - str: configured (settings.DATABASE_MIGRATION_URL or ).strip() return configured or str(settings.DATABASE_URL)未配置时回退到DATABASE_URL这是单角色部署的合理默认。日志会打印实际使用的角色与来源升级时请留意这一行Found N migration files; connecting as role (DATABASE_MIGRATION_URL)如果AISOC_APP_DB_PASSWORD已设置执行器还会在迁移链跑完后顺手把运行时角色的登录口令落到aisoc_app上通过set_config传入不拼接进 SQL。原因是 compose 的 initdb 钩子只在空数据目录时触发就地升级永远走不到它。未设置该变量属于正常状态只记一条 info 日志。5.7 Fly.io 与 Kubernetes 的差异Fly 部署把迁移挂在release_command上见 infra/fly/api/fly.toml先删除哨兵文件再跑迁移成功写出/tmp/aisoc-migrations-ok后才执行seed_demo。软失败数据库不可达时哨兵不写seed 也被跳过——避免 seed 撞上同一个连接错误再崩一次。Kubernetes 的流程同构把 API Deployment 缩到 0用Job跑迁移再扩回来。需要注意文档提到 Helm chart 通过helm upgrade --set runMigrationstrue暴露该能力但在当前离线仓库的 infra/helm/aisoc 模板与 values.yaml 中未检索到runMigrations这个键。因此请以“缩容 Job 扩容”为准并在使用 chart 前用helm show values核对目标 chart 版本是否提供该开关。chart 里确实提供的相关配置是database-migration-url属主 DSN只给迁移用以及AISOC_APP_DB_PASSWORD的三步落地说明。六、v7.3.1 的迁移幂等性历史案例方法论通用文档用一个 :::tip 记录了 v7.3.1 的修复靠近 7.x 的三个迁移——005_compliance.sql、025_connectors_click_and_connect.sql与新增的042_alerts_schema_drift_fix.sql——被改成幂等。若此前升级把alerts表迁到一半直接重跑aisoc db upgrade即可。仓库中的 042_alerts_schema_drift_fix.sql 完整展示了这种写法它把 ORM 模型里声明却从未进 schema 的列补齐BEGIN; -- 实体反范式化 ALTER TABLE alerts ADD COLUMN IF NOT EXISTS affected_ips JSONB NOT NULL DEFAULT []::jsonb; ALTER TABLE alerts ADD COLUMN IF NOT EXISTS affected_hosts JSONB NOT NULL DEFAULT []::jsonb; ALTER TABLE alerts ADD COLUMN IF NOT EXISTS affected_users JSONB NOT NULL DEFAULT []::jsonb; ALTER TABLE alerts ADD COLUMN IF NOT EXISTS affected_assets JSONB NOT NULL DEFAULT []::jsonb; -- 合并 / 父子关系 ALTER TABLE alerts ADD COLUMN IF NOT EXISTS parent_alert_id UUID; ALTER TABLE alerts ADD COLUMN IF NOT EXISTS child_alert_ids JSONB NOT NULL DEFAULT []::jsonb; ALTER TABLE alerts ADD COLUMN IF NOT EXISTS is_merged BOOLEAN NOT NULL DEFAULT FALSE; -- 分派 ALTER TABLE alerts ADD COLUMN IF NOT EXISTS assigned_to_id UUID; ALTER TABLE alerts ADD COLUMN IF NOT EXISTS assigned_at TIMESTAMPTZ; -- 富化 / 标签 ALTER TABLE alerts ADD COLUMN IF NOT EXISTS enrichment_data JSONB NOT NULL DEFAULT {}::jsonb; ALTER TABLE alerts ADD COLUMN IF NOT EXISTS tags JSONB NOT NULL DEFAULT []::jsonb; COMMIT;该文件头注释记录了这个问题的真实症状全新aisoc serveaisoc db upgrade能顺利起栈但GET /api/v1/alerts返回 500因为 asyncpg 找不到alerts.affected_ips、alerts.tags等列。这正是“幂等 只加缺失列”这条设计纪律的由来在公开仓库里迁移应当可重复执行。七、升级后的验证四件事升级成功后以下四项都应通过# 1. 健康与就绪 curl -fsS http://localhost:8000/healthz curl -fsS http://localhost:8000/readyz # 200 且 body 中没有 degraded 服务 # 2. 基准对比 aisoc-cli benchmark # 或 pnpm aisoc:benchmark数值应持平或更好 # 3. 分析师控制台底部显示的版本号与新 tag 一致 # 4. 版本接口返回同一个号 curl -fsS http://localhost:8000/api/v1/system/version/readyz在源码中是一个“阶段化”的就绪探针进程起来即/livez返回 200而/readyz在 lifespan 管理的组件全部完成前返回 503services/api/app/main.py 中对此有明确注释Phase 2.6。所以readyz一直 503 通常意味着某个依赖组件卡住了而不是迁移本身失败。任何一项失败转到 Troubleshooting。八、回滚代码可退schema 不可退这是整篇文档最需要读懂的一段也是最容易踩坑的地方。services/api使用前向-only的 SQL 迁移执行器 services/api/app/scripts/run_migrations.py不是 Alembic没有alembic.ini没有alembic/目录没有 downgrade 概念。全仓只有四个服务使用 Alembic——ueba、honeytokens、purple-team、osquery-tls。这一点可以直接用目录结构验证services/ueba/alembic/ services/honeytokens/alembic/ services/purple-team/alembic/ services/osquery-tls/alembic.ini结论回退代码到上一个 tag 是支持的回退 schema不支持。真正需要旧 schema 的“回滚”等价于恢复升级前清单第 2 步的数据库快照。Patch 与 minor 设计上可干净回滚流程与升级镜像对称git checkout v7.3.0 # 上一个 tag pnpm install --frozen-lockfile (cd services/api uv sync) # 没有 schema downgrade 步骤API 的迁移执行器是前向-only 的。 # 增量式迁移常见情况向后兼容因此旧代码可以跑在新 schema 上。 # 如果某次迁移是破坏性的请改为恢复快照 —— CHANGELOG 会把它标记为不可逆。 docker compose -f docker-compose.yml -f infra/compose/docker-compose.dev.yml up -d api逻辑很清晰绝大多数迁移只是加列、加表、加索引旧代码不读这些新结构所以“旧代码 新 schema”能跑。一旦某个 major 带来单向迁移例如删除列CHANGELOG 会标注 “irreversible”此时唯一回滚路径就是快照。九、跨大版本升级运维必须逐条对照的动作表每跨一个 major 都要读对应那一行。破坏性清单的权威来源是 CHANGELOG 的### BREAKING段下表回答的是“运维要做什么”。从 → 到变化你要做的事any →v10.0.0服务不再以超级用户连接 Postgres92 条行级安全策略开始真正生效。四个自带 alembic 链的服务以属主身份、而非应用角色迁移。用DATABASE_MIGRATION_URL指向属主角色跑迁移。以超级用户连接的服务会绕过全部策略升级前后都要核对连接角色。v10 →v11.0.0POST /v1/ingest与/v1/ingest/batch要求凭据。CORE 需要8 GB 内存、20 GB 磁盘此前约 6.5 GB。升级前先签发 ingest token 并配置到所有生产者否则数据摄入直接停止。先确认宿主机资源余量。v11 →v12.0.0在必需 secret 未设置前actions 服务对所有变更类路由返回 503realtime 边缘拒绝所有连接。启动整套栈之前就把 secret 配好。这两处失败是刻意设计且非常显眼。v12 →v13.0.075 条状态变更路由开始要求此前不需要的权限其中若干条迁移到settings:write而soc_analyst、soc_lead、threat_hunter并未持有该权限。预期出现 HTTP 403——原本返回 200 的调用会失败。升级前就梳理谁需要settings:write。v13 →v14.0.0任何路由都不能授予超出调用者自身权限的角色、scope 或组织成员关系platform_admin与admin无法从任何 API 路由触达。唯一铸造通配角色的方式是针对数据库执行python -m app.scripts.bootstrap_admin。任何通过 API 创建通配角色的自动化都会失效。v14 →v15.0.0/api/v1/shifts被移除/api/v1/threatintel/stix/*的读取在 demo 模式外返回 404。make up启动的是生产级栈AISOC_DEV_MODE不再默认为开启。删除这些路由的调用方它们本来也不承载人工录入的数据。若你依赖开发态认证旁路需显式设置ENVIRONMENTdevelopment原先静默的告警会变成启动拒绝。v15.0.0 →v15.1.0不破坏兼容新增 2 条路由、未移除任何路由。但两处行为明显变化CloudTrail 部署会看到更多告警此前所有事件被折叠成一条告警触发的 playbook 现在真的会执行此前find_matching()没有生产调用方。升级本身无需动作。预期 CloudTrail 告警量回到应有水平升级前检查哪些 playbook 是启用的——从未触发过的 playbook 现在会触发默认以 preview 模式运行需要三项 opt-in 才会真正执行动作。v15.1.0 →v16.0.0cases表消失。迁移 083 把其行移入aisoc_cases重指子表外键并把旧表重命名为cases_pre_consolidation。两张表从未同步控制台写一张、所有 case 指标读另一张导致 MTTR 和 case 计数对分析师创建的每一个 case 都是盲的。另外 SAML/OIDC 登录开始工作——此前因连接表没有写入方而在所有部署上返回 403。检查你自己的 SQL。任何查询cases的东西Grafana 面板、定时导出、报表都必须改读aisoc_cases。它会以 “relation does not exist” 明确失败而不是返回过期数据这是刻意设计。需要对比时归档表可读。升级瞬间 case 指标会变化它们此前是少报而非多报。若使用 SSO先POST /api/v1/sso-connections建连接再放用户进来。v16.0.0 →v16.0.1不破坏兼容。安全发布修复高危提权GHSA-4gx4-x7gm-4xq8判断调用者能否授予权限的检查读的是静态角色而准入路由的检查读的是数据库解析后的权限。当租户用roles/user_roles收窄账号时两者答案不同被收窄的账号可以授予其未收窄角色所携带的任何权限。若你通过数据库 RBAC 限制账号必须升级。没有任何 RBAC 行的部署从未暴露——静态映射对它本就是正确答案。升级后超出调用者实际持有范围的授予会被拒绝因此此前依赖更宽静态角色派发角色的运维会拿到 403应通过 RBAC 授予其权限而不是放宽静态角色。v16.0.1 →v17.0.0移除三条路由POST /detection-loop/suggest与两条GET /detection-loop/suggestions读接口及其三个 schema。无需迁移因为它们从未真正可用——它们查询aisoc_alerts、aisoc_detection_rules与alerts.evidence而这些没有任何迁移创建。等价且受治理的接口是POST /api/v1/detection-proposals。有一个数字改了含义却不报错值得读两遍/api/v1/metrics/dashboard上的alerts.total现在统计未结工作new、triaging、in_progress而不是历史上收到的全部告警相邻的严重度计数同口径。用该字段画累计摄入量的面板会掉到你的队列大小。已结工作单独以alerts.resolved报告。迁移090给aisoc_cases加三个可空列属增量自动执行。删除调用方更新面板口径确认090已跑过。关于 v16 的cases合并源码里能读到完整的设计意图。083_one_case_table.sql 的注释直白写明控制台写aisoc_cases含六态状态机、sla_due_at、evidence_chain、observable_graph而所有指标读casesresolution_time、metrics、insights、executive_digest、mssp_portfolio、GraphQL 查询层于是“分析师创建的每个 case 对所有 case 指标都不可见”。迁移选择保留aisoc_cases并采用可判定的重命名而非 dropIF to_regclass(public.cases_pre_consolidation) IS NULL THEN ALTER TABLE cases RENAME TO cases_pre_consolidation; END IF;这段用to_regclass守卫使全新部署cases可能不存在成为 no-op 而不是报错。同时它还处理了状态词表差异cases.statusopen/resolved…与aisoc_casesnew/triaged/investigating/contained/resolved/closed不同采用映射而非照抄否则落到目标状态机之外的状态会让该 case 在控制台里无法流转。一次跨多个 major 是支持的但未作为单步测试过。请逐个升级、每次之间跑迁移这样出问题时能明确指出是哪个版本导致的。十、版本偏移Version skew的兼容边界在同一个 major 内下列组件在一个 minor 版本的偏移范围内保证线上兼容浏览器 ↔ API 服务API 服务 ↔ 连接器API 服务 ↔ AgentSDK 客户端Go、Python、TypeScript↔ API因此你完全可以把 API 升到6.1.0、连接器仍留在6.0.x花一天完成滚动而不破坏任何东西。跨 major6.x↔7.x契约重置先升 API再升其他组件且必须在同一个维护窗口内完成。这种“API 先行”的纪律与运行时角色分离、RLS 策略是同一套思路的两个侧面schema 是单一事实源API 是唯一懂它的读端其余组件必须跟着 API 的节奏走。十一、长期支持LTS现状AiSOC 目前不提供正式的 LTS 发布。最新 major 就是受支持版本安全补丁与 CVE 修复会在新 major 落地后回溯 90 天到上一个 major——这正是官方预期的运维规划与执行窗口。如果你的环境需要更长支持周期官方建议在 Discussions 中提出愿意讨论商业支持安排。请注意这是政策承诺不是代码行为因此无法在仓库里验证只能以文档为准。十二、Pre-1.0 历史与起点建议1.0.0到5.x是早期功能建设阶段发布的版本记录在 CHANGELOG.md。6.0.02026 年 5 月是第一个被认为可用于生产的版本新部署应从最新 tag 起步文档写作时为v7.3.1而当前工作树VERSION已到20.1.0。这段历史对升级决策的现实意义是1.x–5.x不承诺生产级兼容语义任何从这些版本出发的升级都应视为重建部署而非就地升级——先按目标版本部署一套干净环境再用数据导出/导入迁移业务数据比在旧 schema 上层层叠迁移安全得多。十三、一页速查升级执行清单[准备] □ 读 CHANGELOG当前 → 目标标出 Breaking / Migration / Action required □ pg_dump 备份Kafka / ClickHouse 一并快照 □ 备份 AISOC_CREDENTIAL_KEY丢失即凭据永久不可解 □ 确认维护窗口major 在 audit_log 大表上可能数分钟 □ 预发布租户先升级并观察 24 小时 [执行] □ 入口摘流503停 API 副本连接器 / ingest 可继续 □ git fetch --tags git checkout 目标 tag □ pnpm install --frozen-lockfile □ (cd services/api uv sync) □ 设置 DATABASE_MIGRATION_URL属主角色 DSNv10 □ 设置 AISOC_MIGRATIONS_STRICT1 □ aisoc db upgrade # 或 uv run python -m app.scripts.run_migrations □ docker compose ... up -d api [验证] □ /healthz 200 □ /readyz 200 且无 degraded □ aisoc-cli benchmark 数值持平或更好 □ 控制台页脚版本 /api/v1/system/version 新 tag [跨 major 追加] □ 逐个大版本推进每个之间跑一次迁移 □ 逐行对照“跨大版本动作表” □ 有 SSO 时先建 /api/v1/sso-connections □ 自定义 SQL / Grafana / 导出脚本改读 aisoc_casesv16 起 □ 面板口径确认 alerts.total 只算未结v17 起 [回滚] □ 代码可退回上一 tag前向-only无 schema downgrade □ 需要旧 schema ⇒ 只能恢复快照结语AiSOC 的升级模型可以用三句话概括版本号即契约单一VERSION贯穿 tag、镜像与 SDK迁移前向-only靠真实 SQL 幂等性 aisoc_schema_migrations记账表而不是 down 脚本回滚只退代码不退 schema需要旧结构就还原快照。把AISOC_MIGRATIONS_STRICT1、DATABASE_MIGRATION_URL指向属主角色、以及跨 major 的逐行动作表这三件事做对绝大多数升级事故都可以在发生前被消除。延伸阅读CHANGELOG.md破坏性变更权威清单、迁移执行器、CLI 入口、运行时角色迁移、case 表合并迁移、Fly 发布命令、Helm values。赞分享人工智能AI Agent网络安全后端前端【免费下载链接】AiSOCOpen-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATTCK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.项目地址https://gitcode.com/GitHub_Trending/ai/AiSOC点击查看免费下载相关推荐Service Weaver版本管理与升级如何平滑迁移到新版本Service Weaver版本管理与升级如何平滑迁移到新版本 Service Weaver是一个用于编写和部署云应用的编程框架其版本管理策略确保了应用程序后端微服务云原生RPC框架开发工具如何快速上手LitePCIe从安装LiteX环境到生成第一个PCIe核心的5步教程如何快速上手LitePCIe从安装LiteX环境到生成第一个PCIe核心的5步教程 LitePCIe 是一款由 EnjoyDigital 开发的小面积、可配置用 Dify 零代码搭建电商文案生成应用10 分钟从 0 到 1 跑通用 Dify 零代码搭建电商文案生成应用10 分钟从 0 到 1 跑通 运营同事刚把第 37 条商品标题改完。商品名、卖点、人群都填进表格文案却总差一口气。人工智能大模型AI 应用AI AgentRAG后端前端工作流自动化低代码上一篇掌握CANN ClipByValue算子从数据安全到性能优化的完整指南下一篇Noodle平台技术债务管理保持教育项目健康的长期策略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考