开发环境搭建

本页用于源码开发和本地调试。生产或单机私有化部署请优先使用部署中的 Docker Compose 发布包。

本文默认使用 Linux/macOS shell。开发环境建议拆开运行：依赖服务用 Docker Compose，后端和前端在本机直接启动。这样方便调试代码、看日志、改前端和单独启动某个 Worker。

1. 进程和端口

ASP 本地开发会涉及三类后端进程：

进程	默认端口	职责
WSGI / Django	`8000`	可选的 Django REST API 入口，直接处理 `/api/`。
ASGI / Django + WebSocket	`8001`（可调整）	Vite 默认代理目标，同时处理 `/api/` 和 `/ws/`。
Workers	—	后台任务：Module 消费、Case 分析、Playbook 执行、ELK 轮询和 Dashboard 缓存。

路由关系：

text

/api/*    -> ASGI / Django（Vite 默认）
/ws/*     -> ASGI / WebSocket

生产环境中 ASGI 容器内部使用 8001。本地如果同时启用 Redis Stack UI 并占用 8001，可以为 ASGI 选择其他空闲端口，并同步更新 frontend/vite.config.ts 的 /api 和 /ws 代理。

2. 启动依赖服务

开发环境的 PostgreSQL、Redis Stack 和 RustFS 可以用 development/docker 启动：

bash

cd /path/to/agentic-soc-platform/development/docker
cp .env.example .env
docker compose up -d

启动后可用服务：

服务	地址	用途
PostgreSQL	`localhost:5432`	后端数据库。
Redis	`localhost:6379`	Cache 和 Redis Stream。
Redis Stack UI	`http://localhost:8001`	Redis Web 管理界面。
RustFS S3 API	`http://localhost:9000`	附件和头像使用的 S3 兼容接口。
RustFS Console	`http://localhost:9001`	RustFS Web 管理界面。

如果端口被占用，优先调整 development/docker/.env 或 Compose 端口映射，再启动依赖服务。

3. 配置后端 `.env`

进入 backend，从示例文件创建本地 .env：

bash

cd /path/to/agentic-soc-platform/backend
cp .env.example .env

至少确认这些配置和 development/docker/.env 一致：

text

DJANGO_SECRET_KEY=dev-secret-key
DJANGO_DEBUG=true
DJANGO_ALLOWED_HOSTS=*

POSTGRES_DB=asp
POSTGRES_USER=postgres
POSTGRES_PASSWORD=asp-dev-postgres-password
POSTGRES_HOST=localhost
POSTGRES_PORT=5432

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=1
REDIS_PASSWORD=asp-dev-redis-password

RUSTFS_ENDPOINT_URL=http://localhost:9000
RUSTFS_ACCESS_KEY=asp
RUSTFS_SECRET_KEY=asp-dev-rustfs-password
RUSTFS_BUCKET=asp
RUSTFS_REGION=us-east-1

这些值只适合本地开发。生产环境必须使用随机密钥和受控密码。

4. 初始化后端

安装依赖、执行迁移并创建管理员：

bash

uv sync
.venv/bin/python manage.py migrate
.venv/bin/python manage.py createsuperuser

常用检查：

bash

.venv/bin/python manage.py check
.venv/bin/python manage.py test

后端依赖由 uv 管理。运行管理命令时优先使用 backend/.venv/bin/python。

5. 启动后端 API

最常用方式是 Django 开发服务器：

bash

.venv/bin/python manage.py runserver 0.0.0.0:8000

启动后：

API: http://localhost:8000/api/

如果需要更接近生产环境，可以使用 Gunicorn：

bash

.venv/bin/gunicorn asp.wsgi:application --bind 0.0.0.0:8000 --reload

6. 启动 ASGI / WebSocket

ASGI 进程同时提供 Django HTTP API 和实时事件 WebSocket，也是 Vite 的默认后端：

bash

.venv/bin/uvicorn asp.asgi:application --host 0.0.0.0 --port 8001 --reload

ASGI 路由：

text

/ws/*  -> 实时事件 WebSocket
/api/* -> Django HTTP API
/      -> Django fallback

如果 8001 已被 Redis Stack UI 占用，改用其他空闲端口，并同步更新前端 /api 和 /ws 代理。

7. 启动 Workers

按需启动后台进程：

bash

.venv/bin/python manage.py run_agentic_module_worker
.venv/bin/python manage.py run_agentic_case_analysis_worker
.venv/bin/python manage.py run_agentic_playbook_worker
.venv/bin/python manage.py run_elk_action_worker
.venv/bin/python manage.py run_dashboard_cache_worker

Worker	作用
`run_agentic_module_worker`	消费 Redis Stream，运行 Module 生成 Case / Alert / Artifact。
`run_agentic_case_analysis_worker`	执行 Case AI 分析任务。
`run_agentic_playbook_worker`	执行用户触发的 Playbook。
`run_elk_action_worker`	从 ELK Action Index 轮询告警。
`run_dashboard_cache_worker`	定时生成 Dashboard 24h、7d 和 30d 缓存。

Dashboard 依赖 run_dashboard_cache_worker 生成首个缓存；未启动时 Dashboard 会返回 503。只开发其他前端列表页时，可以不启动该 Worker。

8. 启动前端

进入 frontend 安装依赖并启动 Vite：

bash

cd /path/to/agentic-soc-platform/frontend
pnpm install
pnpm dev

默认访问：

text

http://localhost:5173

默认 Vite 代理：

text

http://localhost:5173/api/*  ->  http://localhost:8001/api/*
ws://localhost:5173/ws/*     ->  ws://localhost:8001/ws/*

如果 ASGI 使用其他端口，需要同步修改 vite.config.ts：

typescript

server: {
  proxy: {
    '/api': { target: 'http://localhost:8002', changeOrigin: true },
    '/ws': { target: 'ws://localhost:8002', ws: true },
  },
}

前端修改不需要主动执行 npm build，除非明确要求验证构建。

9. 前后端请求链路

开发环境：

text

Browser (localhost:5173)
  -> Vite proxy
    -> /ws/*     -> ASGI (localhost:8001 或自定义端口)
    -> /api/*    -> ASGI / Django (localhost:8001 或自定义端口)

生产环境：

text

Browser (443)
  -> Nginx
    -> /ws/*     -> ASGI (asp-asgi:8001)
    -> /api/*    -> WSGI / Django (asp-web:8000)
    -> /*        -> Frontend static files

10. Custom 目录

源码开发时，backend/custom/ 与 Compose 发布包中的 custom/ 目录结构保持一致：

text

backend/custom/
  modules/
  playbooks/
  data/
    modules/
    siem/
    playbooks/
  requirements.txt

backend/custom/modules/：自定义 Module。
backend/custom/playbooks/：自定义 Playbook。
backend/custom/data/siem/：自定义 SIEM YAML。
backend/custom/data/playbooks/：自定义 Playbook Prompt。
backend/custom/requirements.txt：自定义代码需要的额外 Python 包。

测试自定义依赖时，可以安装到本地 custom package 目录，并加入 PYTHONPATH：

bash

mkdir -p .custom-packages
uv pip install --python .venv/bin/python --target .custom-packages -r custom/requirements.txt
export PYTHONPATH="$(pwd)/.custom-packages:$(pwd)/custom"

修改脚本或 YAML 后，可以在 ASP 前端的 Custom Console 中执行 Refresh / Validate。

下一步

Mock 数据 — 生成工作台数据或 SIEM 测试日志。
Custom Console — 刷新并校验本地加载的定制定义。
Module 开发 — 编写自定义告警处理 Module。
Playbook 开发 — 编写从 Case 触发的自动化任务。

Records

Integrations

Authoring

Investigation Workflows

开发环境搭建

1. 进程和端口

2. 启动依赖服务

3. 配置后端 `.env`

4. 初始化后端

5. 启动后端 API

6. 启动 ASGI / WebSocket

7. 启动 Workers

8. 启动前端

9. 前后端请求链路

10. Custom 目录

下一步

开发环境搭建 ​

1. 进程和端口 ​

2. 启动依赖服务 ​

3. 配置后端 .env ​

4. 初始化后端 ​

5. 启动后端 API ​

6. 启动 ASGI / WebSocket ​

7. 启动 Workers ​

8. 启动前端 ​

9. 前后端请求链路 ​

10. Custom 目录 ​

下一步 ​

开发环境搭建

1. 进程和端口

2. 启动依赖服务

3. 配置后端 `.env`

4. 初始化后端

5. 启动后端 API

6. 启动 ASGI / WebSocket

7. 启动 Workers

8. 启动前端

9. 前后端请求链路

10. Custom 目录

下一步