企业官网建设流程全解析

Obsius-AI：AI驱动全能安全平台，小白程序员必备网络安全学习利器（收藏版）

Obsius-AI 是一个AI驱动的全能安全平台，涵盖渗透测试、红队、CTF、二进制逆向、Pwn、IoT与AI安全等方向。平台采用前后端分离+反向代理的轻量架构，支持单代理和多代理运行态，具有发现常驻（黑板）功能，可复用项目，方便用户学习和实践网络安全技能。平台目前处于迭代期，功能尚未完全收尾，存在一些bug，但适合小白和程序员学习网络安全知识。

Obsius-AI 项目

一、技术架构

======

1. 项目定位

Obsius-AI 是一个AI 驱动的全能安全平台，覆盖渗透测试、红队、CTF、二进制逆向（Reverse）、Pwn、IoT 与 AI 安全等方向，原生 Windows 优先（项目 requires-python >= 3.11，依赖链大量面向 Windows）。

核心理念（来自 README / DESIGN.md）：

单代理 / 多代理（Multi-Agent）两种运行态：既可以让一个 Agent 独立完成链路，也可以编排多个 Agent 协作。

发现常驻（黑板 Blackboard）：所有“发现/资产/证据”写入一个可复用的统一知识库，跨会话、跨任务沉淀，避免重复劳动。

可复用项目（Project）：把目标、资产、情报、剧本（pack）组织成项目，随取随用。

项目明确处于迭代期，关键功能未收尾、存在较多 bug，文档与代码细节可能随版本变动。

2. 整体架构

采用前后端分离 + 反向代理的轻量架构，不是单体程序：

┌─────────────────────────┐ ┌──────────────────────────────┐ │ 浏览器 (用户) │ │ 后端 API (FastAPI/uvicorn) │ │ http://localhost:5173 │ /api/* │ 127.0.0.1:8420 │ │ ───────────────────── │ ──────▶ │ scripts/serve.py │ │ Vite dev (React SPA) │ 代理 │ core/api/app.py (create_app) │ │ + HMR 热更新 │ ◀────── │ └─ 核心引擎 core/* │ └─────────────────────────┘ └──────────────────────────────┘ 前端进程 (Node) 后端进程 (Python .venv)

前端：Vite 开发服务器（端口 5173），提供 React 单页应用（SPA），通过 vite.config.ts 把 /api 代理到后端 8420，浏览器无跨域。

后端：uvicorn 拉起 FastAPI 应用，仅监听 127.0.0.1（本机，不暴露公网）。

进程关系：两者是两个独立进程。官方 .bat 与本地手动启动本质都是分别拉起这俩进程。

后端进程内的应用由 core.api.create_app(workspace_root, packs_root, tools_root, static_dir) 构建，在内存中常驻维护：

项目库（ProjectStore）

Agent 会话表

浏览器实例池（BrowserPool）

IDA-MCP 管理器（IdaMcpManager）

LLM 供应商路由（ModelRouter / ProviderStore）

3. 技术栈

后端（Python）

前端（Node / TypeScript）

4. 后端核心模块（core/）

core/ 是平台的“大脑”，按职责划分子包。核心引擎零第三方依赖，只有 API 层与可选能力组才 import 外部库。

5. 启动形态

scripts/serve.py 是统一入口，支持多种形态（详见文件 docstring）：

无窗模式（默认）：

python scripts/serve.py → 起 127.0.0.1:8420，控制台看日志。

2. 窗口模式（桌面壳）：

python scripts/serve.py --window → 用 pywebview + WebView2 弹原生窗口；端口已在跑则 attach（附窗连已有服务），否则 owner（本进程拉起服务）。最后一窗关闭触发优雅停机。

3. 静态同源模式（M2）：先

cd webui && npm run build 生成 webui/dist，再起服务 → 后端在 8420 同源托管整个 UI（/ 即 WebUI），无需单独 Vite。

4. 打包 exe（M3，预留）：scripts/build_exe.py 冻结为 exe，双击即窗口模式。

优雅停机：进程持有 uvicorn Server 句柄并注册 POST /api/admin/shutdown（置 should_exit），FastAPI shutdown 钩子趁机关闭时给所有在跑会话落断点快照，重启不丢现场（配合 core/agent/loop 的 task_resume_path）。

6. 数据存储布局

serve.py 在启动时会 os.chdir(_ROOT)（项目根），以下均为相对于项目根的路径惯例：

7. API 概览

全部接口以 /api 为前缀（如 GET /api/projects、POST /api/admin/shutdown），共约 177 个路由。

交互式文档：

http://127.0.0.1:8420/docs Swagger%20UI%EF%BC%89/%20http://127.0.0.1:8420/redoc%E3%80%82

启动本身不依赖LLM key；但真正跑 AI 任务前需在 config/providers.json 配置供应商（PUT /llm/providers 可在运行时写入）。

8. 设计要点 / 兼容性注意

核心引擎零依赖：只有 core/api/ 依赖 FastAPI；可选能力（浏览器/窗口）按依赖组隔离、缺失即降级，import 不炸。

降级策略贯穿全局：Playwright 缺失 → 浏览器链 no-tool；openpyxl 缺失 → xlsx 导入 503 但 CSV 可用；pywebview/WebView2 缺失 → 回退无窗模式。

版本敏感点：项目代码使用 Starlette 0.37.x 才有的 app.add_event_handler，而 uv.lock 可能被升级到新版本（Starlette 1.6 / FastAPI 0.141 已移除该 API），直接启动会 AttributeError。需用兼容组合（见第二部分 §2.3）。

Windows 优先：路径、窗口壳、WebView2、IDA/反编译等大量面向 Windows；在非 Windows 上部分能力不可用（如窗口模式会回退）。

二、运行指南

======

本文命令基于本机实际路径：/Obsius-AI-main 下文用 <项目根> 指代该路径。Windows 命令示例用 cmd（反斜杠）；Git Bash 亦可，但要注意路径/编码差异。

0. 一句话启动（已就绪时）

后端依赖已装好、.venv 已存在的前提下，分别拉起两个进程即可：

:: 终端 1 — 后端 (8420)cd /d <项目根>.venv/Scripts/python.exe scripts/serve.py:: 终端 2 — 前端 (5173)cd /d <项目根>/webuinpm run dev -- --port 5173 --strictPort

【

值得注意的是5173端口可能被其他项目使用，建议更换端口，如：

npm run dev – --port 5177 --strictPort

】

浏览器打开http://localhost:5173/。下面是从零开始的标准流程。

1. 环境要求

Python≥ 3.11（本机 3.13；建议用 uv 管理虚拟环境）

Node.js≥ 18（本机 Node 22）+ npm

uv（Python 包/虚拟环境管理，官方 uv.lock 锁定依赖）

操作系统：原生Windows 优先（窗口模式/IDA/WebView2 等能力仅 Windows 完整）

2. 后端启动（端口 8420）

2. 1 建虚拟环境

cd /d <项目根>uv venv --python 3.13

生成 <项目根>.venv。

2. 2 安装后端依赖（关键：不要直接 uv sync）

⚠️ uv sync 会尝试构建 window 组的 pywebview → proxy-tools，在 Windows 上会因回收站删除报错而失败。无窗口需求时手动只装运行所需依赖：

uv pip install ”fastapi>=0.110” ”uvicorn>=0.29” ”httpx>=0.27” ”python-multipart>=0.0.9” ”openpyxl>=3.1”

2. 3 版本降级（关键：否则启动即报错）

⚠️ 项目代码使用了 Starlette 0.37.x 才有的 app.add_event_handler(“shutdown”, …)，而新版 Starlette（0.38+）已移除该 API，若装到 FastAPI 0.141 / Starlette 1.6 会 AttributeError: ‘FastAPI’ object has no attribute ‘add_event_handler’。

必须降级到兼容组合：

uv pip install ”fastapi==0.111.0” ”starlette==0.37.2”

（验证：uv pip show starlette 应显示 0.37.2；fastapi 0.111.0 允许 starlette 0.37.2。）

2. 4 启动后端

cd /d <项目根>.venv/Scripts/python.exe scripts/serve.py

成功后会看到：

obsius core API -> http://127.0.0.1:8420 文档: http://127.0.0.1:8420/docs Application startup complete.

默认端口 8420，可用 scripts/serve.py 8421 改端口。

–window

可起桌面窗口壳（需 pywebview + WebView2）。

首次启动会自动创建 workspaces/。

3. 前端启动（端口 5173）

3. 1 安装依赖

cd /d <项目根>/webuinpm install

3. 2 启动 Vite 开发服务器

cd /d <项目根>/webuinpm run dev -- --port 5173 --strictPort

默认即 5173；–strictPort 表示端口被占则报错而非换端口。

启动后 vite.config.ts 自动把 /api 代理到 127.0.0.1:8420，前端无需知道后端真实地址、无跨域。

4. 访问地址

只访问 5173 即可；前端通过代理把 /api/* 转发到 8420。

5. 停止服务

方式 A（推荐，已修复）：双击项目根目录停止平台.bat。它会先 POST /api/admin/shutdown 优雅停机（落快照），再按端口 taskkill 掉前端。

方式 B（手动）：直接结束两个终端的后台进程（serve.py 与 vite）。

方式 C（优雅单停后端）：

POST http://127.0.0.1:8420/api/admin/shutdown 。

⚠️ 历史上四个 .bat（停止平台 / 启动平台 / 启动新UI / 启动平台（窗口））是 UTF-8 无 BOM，在部分 Windows 上 chcp 65001 自举无法可靠重读，导致中文被当 GBK 误解析成乱码命令。已给它们加上 UTF-8 BOM 修复；现在双击即可正常用。

6. 已踩坑速查（排错）

7. 配置 LLM 供应商

启动本身不依赖API key，但真正驱动 Agent 需要配置 LLM：

配置文件：<项目根>/config/providers.json

运行时写入：PUT /api/llm/providers（后端在请求时惰性读取，不影响启动）

在 WebUI 的设置页也能填。配置后模型路由（core/llm/routing 的 KNOWN_ROLES）才能按角色（如 planner/executor）选模型。

8. 可选：单端口静态托管

把前端构建进后端同源端口，只需一个进程一个端口（8420）：

:: 1) 构建前端cd /d <项目根>/webuinpm run build :: 生成 webui/dist:: 2) 只起后端（自动同源托管 /）cd /d <项目根>.venv/Scripts/python.exe scripts/serve.py

之后浏览器直接访问http://127.0.0.1:8420/（无需再开 Vite）

9. 验证清单（启动后自检）

:: 后端文档可达curl http://127.0.0.1:8420/openapi.json :: 应返回 JSON，含 ~177 个路径:: 前端页面可达curl http://localhost:5173/ :: 应返回含 的 HTML:: 经代理端到端curl http://localhost:5173/api/projects :: 应 200，返回项目列表（初始为空）

全部通过即代表前后端已连通，可正常使用平台。

项目截图 ：

模型添加：

项目地址 ：

https://github.com/ILOVCTRY/Obsius-AI

互动话题：如果你对网络攻防技术感兴趣，想学习更多网安方面的知识和工具，可以看看以下题外话！

题外话

黑客/网络安全学习路线

今天只要你给我的文章点赞，我私藏的网安学习资料一样免费共享给你们，来看看有哪些东西。

网络安全学习资源分享:

下面给大家分享一份2026最新版的网络安全学习路线资料，帮助新人小白更系统、更快速的学习黑客技术！

一、2026最新网络安全学习路线

一个明确的学习路线可以帮助新人了解从哪里开始，按照什么顺序学习，以及需要掌握哪些知识点。

对于从来没有接触过网络安全的同学，我们帮你准备了详细的学习成长路线图&学习规划。可以说是最科学最系统的学习路线，大家跟着这个大的方向学习准没问题。

**读者福利 |***CSDN大礼包：《网络安全入门&进阶学习资源包》免费分享 *（安全链接，放心点击）

我们把学习路线分成L1到L4四个阶段，一步步带你从入门到进阶，从理论到实战。

L1级别:网络安全的基础入门

L1阶段：我们会去了解计算机网络的基础知识，以及网络安全在行业的应用和分析；学习理解安全基础的核心原理，关键技术，以及PHP编程基础；通过证书考试，可以获得NISP/CISP。可就业安全运维工程师、等保测评工程师。

L2级别：网络安全的技术进阶

L2阶段我们会去学习渗透测试：包括情报收集、弱口令与口令爆破以及各大类型漏洞，还有漏洞挖掘和安全检查项目，可参加CISP-PTE证书考试。

L3级别：网络安全的高阶提升

L3阶段：我们会去学习反序列漏洞、RCE漏洞，也会学习到内网渗透实战、靶场实战和技术提取技术，系统学习Python编程和实战。参加CISP-PTE考试。

L4级别：网络安全的项目实战

L4阶段：我们会更加深入进行实战训练，包括代码审计、应急响应、红蓝对抗以及SRC的挖掘技术。并学习CTF夺旗赛的要点和刷题

整个网络安全学习路线L1主要是对计算机网络安全的理论基础的一个学习掌握；而L3 L4更多的是通过项目实战来掌握核心技术，针对以上网安的学习路线我们也整理了对应的学习视频教程，和配套的学习资料。

二、技术文档和经典PDF书籍

书籍和学习文档资料是学习网络安全过程中必不可少的，我自己整理技术文档，包括我参加大型网安行动、CTF和挖SRC漏洞的经验和技术要点，电子书也有200多本，（书籍含电子版PDF）

三、网络安全视频教程

对于很多自学或者没有基础的同学来说，书籍这些纯文字类的学习教材会觉得比较晦涩难以理解，因此，我们提供了丰富的网安视频教程，以动态、形象的方式展示技术概念，帮助你更快、更轻松地掌握核心知识。

网上虽然也有很多的学习资源，但基本上都残缺不全的，这是我自己录的网安视频教程，上面路线图的每一个知识点，我都有配套的视频讲解。

四、网络安全护网行动/CTF比赛

学以致用，当你的理论知识积累到一定程度，就需要通过项目实战，在实际操作中检验和巩固你所学到的知识，同时为你找工作和职业发展打下坚实的基础。

五、网络安全工具包、面试题和源码

“工欲善其事必先利其器”我为大家总结出了最受欢迎的几十款款黑客工具。涉及范围主要集中在 信息收集、Android黑客工具、自动化工具、网络钓鱼等，感兴趣的同学不容错过。

面试不仅是技术的较量，更需要充分的准备。

在你已经掌握了技术之后，就需要开始准备面试，我们将提供精心整理的网安面试题库，涵盖当前面试中可能遇到的各种技术问题，让你在面试中游刃有余。

如果你是要找网安方面的工作，它们绝对能帮你大忙。

这些题目都是大家在面试深信服、奇安信、腾讯或者其它大厂面试时经常遇到的，如果大家有好的题目或者好的见解欢迎分享。

参考解析：深信服官网、奇安信官网、Freebuf、csdn等

内容特点：条理清晰，含图像化表示更加易懂。

内容概要：包括 内网、操作系统、协议、渗透测试、安服、漏洞、注入、XSS、CSRF、SSRF、文件上传、文件下载、文件包含、XXE、逻辑漏洞、工具、SQLmap、NMAP、BP、MSF…

**读者福利 |***CSDN大礼包：《网络安全入门&进阶学习资源包》免费分享 *（安全链接，放心点击）