上一篇我们把架构和取舍讲透了分级存储、拉模型采集、AI 消费点。老李也把那台 2019 年的旧服务器从库房搬了出来装上了 Linux。那么这一篇回答动手的人最关心的问题从一台裸机到登录进自己的 SOC 控制台到底要几步、会卡在哪先交代一件事这篇文章是写给使用者的——你的目标是用上它不是给它提交代码。所以全文只有一条主线“把它跑起来、用起来”。至于开发者才需要的东西跑测试、本地开发环境文末有个进阶彩蛋指个路平时你完全不需要碰。结论先行核心链路 5 步、顺利的话 45 分钟。但顺利是有条件的——这篇文章除了正常步骤还会把我部署时踩过的每一个坑原样交给你因为坑才是部署教程真正值钱的部分官方文档从来不会写你会在这里卡 20 分钟。老规矩先看全景再动手一个重要原则每一步都有明确的过关标准过了再走下一步。这样新手最大的敌人——“好像都装了但不知道哪里不对”——就无处藏身出问题时你永远知道卡在哪一格。第 0 步环境准备10 分钟老李的旧服务器装的是 Ubuntu 22.04Debian 12 也行先确认这五样东西# 1. Gitgit--version# 2. Python 3.13注意不是 3.12项目锁定 3.13python3.13--version# 3. Node.js 18 和 npm 9前端构建用项目不用 pnpmnode-vnpm-v# 4. PostgreSQL 16psql--version# 5. Docker Docker Compose跑采集器dockerpsdockercompose version过关标准五条命令都有正常输出没有 command not found。Ubuntu 22.04 默认源里的 Python 是 3.10装 3.13 要用 deadsnakes PPA。这是第 0 步最常见的坑但网上教程很多不展开。然后克隆代码gitclone https://github.com/xiejava1018/AI-miniSOC.gitcdAI-miniSOC第 1 步建一个生产库2 分钟使用者只需要一个数据库sudo-upostgres psql-cCREATE DATABASE AI-miniSOC-db;过关标准sudo -u postgres psql -c \l能在列表里看到AI-miniSOC-db。就这么简单。README 里一次建三个库的写法是给项目贡献者准备的本地开发库、pytest 测试库都是改代码的人才用得上——你现在不需要一个库就是全部。这也是使用者的天然优势只有一个库就不存在测试数据误删生产表这种事故配置永远不会指错地方。第 2 步后端启动10 分钟——坑最密集的一步2.1 虚拟环境与依赖cdsrc/backend python3.13-mvenv../../venv# venv 建在仓库根目录项目约定位置../../venv/bin/pipinstall-rrequirements.txt2.2 配置 .envcp.env.example .env.env长什么样、哪些必填哪些可空先看配置地图起步只需填两组其余全部保留占位符跑通再补# 数据库组第 1 步建的DB_HOSTlocalhostDB_PORT5432DB_NAMEAI-miniSOC-dbDB_USERpostgresDB_PASSWORD你的数据库密码# 认证组JWT 签名密钥生产必须换掉默认值SECRET_KEY一串足够长的随机字符串⚠️.env的键名必须与app/core/config.py里Settings类的字段1:1 对应。自己发明键名不会报错——它只是静默不生效然后你在为什么连不上数据库上浪费一小时。这是.env最阴的坑。2.3 初始化数据库表alembic——新手必卡点 #1../../venv/bin/python-malembic-calembic.ini upgradehead这条命令会把 52 张soc_前缀的表建到DB_NAME指向的库里。跳过这步的后果后端能启动但登录直接 500因为没有用户表。2.4 启动后端# ⚠️ 必须从 src/backend/ 目录启动.env 的加载依赖工作目录../../venv/bin/python-muvicorn main:app--host0.0.0.0--port8000# 另开终端健康检查curlhttp://localhost:8000/health过关标准health 接口返回正常浏览器打开http://localhost:8000/docs能看到 Swagger 接口文档43 个路由模块的分组列表。curl http://localhost:8000/health健康检查结果——返回 JSON 就是活的浏览器打开http://localhost:8000/docsSwagger 接口文档长这样左侧分组可以逐个展开️新手必卡点 #2本篇最大的坑如果你不是从src/backend/目录启动——比如图省事在仓库根目录跑uvicorn src.backend.main:app——程序照样能启动但.env根本没被加载。症状是一堆数据库/Redis 连接错误报错信息完全指向错误的方向。记住口诀进到 src/backend 里面再启动。第 3 步前端启动15 分钟cdsrc/frontendnpminstall# 前端依赖项目固定用 npm 不用 pnpmnpmrun dev# 开发服务器浏览器打开 http://localhost:3006过关标准http://localhost:3006出现登录页且能登录进控制台看到左侧 11 个菜单。登录页注意有验证码——这是后端登录硬化的一部分登录成功后默认进入概览仪表盘——这就是部署完成的标志性瞬间从裸机到这里45 分钟️坑 #3npm install在国内网络环境可能极慢或失败——换 npm 镜像源npm config set registry https://registry.npmmirror.com可以解决 90% 的情况。用起来了然后呢从开发模式切到生产模式npm run dev是开发模式——适合验证链路但长期用比如给同事开账号、挂到服务器常跑应该切到生产模式静态文件 nginx 托管速度更快、资源占用更低、重启自动拉起npx vite build# 构建产物在 dist/# 用 nginx 托管 dist/ 并反代 /api 到 :8000生产部署形态️坑 #4进阶玩家才会遇到别用npm run build——它带的vue-tsc类型检查必挂项目已知的类型欠账不影响功能。生产构建直接npx vite build。README 里写了这一点但很多人不看这一行然后卡半天。到这里核心链路已经打通——你现在有一个能登录、能看板的 SOC 了。下面是加分项。第 4 步可选基础设施三件套Wazuh / Loki / Grafana 这些基础设施项目提供了懒人包./scripts/install/install.sh# 自动部署 Wazuh / Loki / Grafana装完后在控制台配置中心 → 数据源管理里配置三个数据源的地址对应.env的基础设施组看到状态灯变绿即接入成功为什么标可选不装 Wazuh/Loki平台照样跑告警和日志相关页面会是空的但不崩——这正是 01 篇组件可独立替换架构的现实好处。你可以先把平台跑起来、熟悉界面再用一个周末把基础设施补上。分两次吃每次都是小口。进阶彩蛋三个库的世界想改代码的那天再看今天你只建了一个库。但如果哪天你不满足于用开始想改——给项目修个 bug、加个小功能甚至提个 PR——那天你需要回来补建两个库库什么时候需要AI-miniSOC-db生产第一天就要 ✅你已经有了AI-miniSOC-testdb本地开发你开始在本地改代码、起开发后端的那天AI-miniSOC-db_testpytest你想跑项目测试套件的那天通常是想提 PR 时为什么那时候要分库因为改代码的世界里存在真实的事故形态本地改.env时把DB_NAME指到生产库随手跑了个会删表重建的测试——生产资产台账瞬间清空。三个库就是三条平行车道分开是纪律混着是事故。这也是这个项目有意思的地方使用者和贡献者之间隔的只是两条 CREATE DATABASE 命令。哪天你跨过去了欢迎——那是 [第 18 篇路线图与共建] 要讲的故事。踩坑总表对号入座用把这次的坑集中列一遍部署卡住时直接对表#症状根因解法1后端启动报一堆数据库连接错误不在src/backend/目录启动.env没加载cd src/backend再启动2登录接口 500alembic 迁移没跑库里没表alembic upgrade head3npm install卡死/失败国内网络换 npmmirror 镜像源4npm run build类型报错挂掉vue-tsc 已知类型欠账生产构建用npx vite build5Python 3.13 装不上Ubuntu 22.04 默认源没有deadsnakes PPA6改了 .env 不生效键名拼写与 Settings 字段不一致静默失败对照app/core/config.py逐个检查这张表以后会持续更新——你在部署中踩到的新坑欢迎到仓库提 Issue我会补进表里并注明出处。踩坑记录本身就是这个开源项目给后来者最实在的礼物。部署完成之后先做这三件事跑起来只是起点。接下来建议按顺序做三件事把这个能跑的系统变成你的系统改默认密码 确认 SECRET_KEY 已换——安全系统的第一课是保护自己接入第一台主机找一台你的服务器装 Wazuh agent看它的日志和告警第一次流进你的控制台——那一刻你会真正理解自己的 SOC是什么感觉具体步骤是 [下一篇 (03)] 的内容配置一条推送通道邮件或钉钉然后故意触发一条告警测试全链路——打通告警 → 通知到你手机的闭环SOC 才算活了。写在最后00 篇我们想清楚为什么做01 篇看懂凭什么做得动这一篇把它跑了起来。回头看这 45 分钟五步路线、一个数据库、两组必填配置、四个坑。这些数字都不吓人——吓人的从来不是步骤数而是不知道自己卡在哪。所以本篇反复强调的就是一件事每步设过关标准过了再走。下一篇 (03)Wazuh 接入实战——把你的第一台主机纳管进来。从装 agent、跑通第一条告警到我那七篇 Wazuh 教程没写的平台化集成经验Webhook 实时同步 vs 手动全量的取舍。老李的服务器已经跑起来了你的呢【系列导航】《一个人的SOC》总目录持续更新【上一篇】(01) 总体架构——8G 内存的小服务器如何装下一个 SOC【系列开篇】(00) 中小企业为什么需要自己的安全运营中心【项目地址】AI-miniSOC - GitHub · MIT 开源欢迎 Star ⭐https://github.com/xiejava1018/AI-miniSOC【交流】部署卡住了把你卡住的报错截图发到仓库 Issue我会逐个回复——典型问题会写进下一篇的踩坑表。下一篇预告(03) Wazuh 接入实战——把第一台主机纳管进来连载中敬请关注作者博客http://xiejava.ishareread.com/