定制内容部署

本页说明如何把自定义 Module、Playbook、SIEM YAML 和 Python 依赖交付到 Docker Compose 部署。首次安装 ASP 请先完成部署。

1. 定制目录

Compose 发布包把宿主机的 custom/ 挂载到后端容器。按用途放置文件：

路径	用途
custom/modules/*.py	自定义 Module。
custom/playbooks/*.py	自定义 Playbook。
custom/data/modules/<module_slug>/raw_alert_*.json	Module 开发调试样本。
custom/data/siem/*.yaml	自定义 SIEM YAML。
custom/data/playbooks/<playbook_slug>/*.md	自定义 Playbook Prompt。
custom/requirements.txt	Module、Playbook 或公共 helper 所需的额外 Python 包。

init.sh 会创建空的 custom/ 目录结构和 custom/requirements.txt 模板。源码仓库中的 backend/custom/ 仅用于本地开发参考，不会随发布包交付示例内容。

2. 安装 Python 依赖

把额外依赖写入：

custom/requirements.txt

在现有 Compose 部署中安装：

docker compose run --rm asp-custom-deps

依赖会安装到 /opt/asp/custom-packages，该目录由 custom-python-packages Docker named volume 持久化，并挂载到全部后端服务。

如需指定 Python package index，把参数放在服务名后：

docker compose run --rm asp-custom-deps --index-url https://pypi.org/simple

服务名后的参数会传给 uv pip install，例如：

• --extra-index-url https://packages.example.com/simple：增加额外的 Python package index。
• --upgrade：升级已安装的依赖。

如需通过代理安装依赖，把代理环境变量传入容器：

docker compose run --rm \
  -e HTTP_PROXY=http://proxy.example:8080 \
  -e HTTPS_PROXY=http://proxy.example:8080 \
  asp-custom-deps

3. 应用变更

只修改 Module、Playbook 或 SIEM YAML 时，在 Custom Console 对应 Tab 中执行 Refresh / Validate。

修改 custom/requirements.txt 或公共 helper module 后，重新安装依赖并重启使用定制代码的服务：

docker compose run --rm asp-custom-deps
docker compose restart asp-web asp-worker-module asp-worker-playbook
./scripts/doctor.sh

4. Compose 覆盖配置

init.sh 会在文件不存在时创建 compose.override.yaml。Docker Compose 会自动将它与官方 compose.yaml 合并。

• 密码、端口和镜像等已有设置写入 .env。
• 定制代码需要增加 volume、环境变量、command 或其他服务级配置时，编辑 compose.override.yaml。
• 不要直接修改官方 compose.yaml。

例如，为 Web 服务增加定制环境变量：

services:
  asp-web:
    environment:
      EXAMPLE_SETTING: value

修改后重新创建受影响的容器：

docker compose up -d
./scripts/doctor.sh

发布包不包含 .env、compose.override.yaml 和 custom/，解压升级时会保留这些内容。升级流程见升级。

下一步

• Custom Console — 查看定制定义的加载状态并执行刷新校验。
• Module 开发 — 编写 Redis Stream 消费逻辑。
• Playbook 开发 — 编写 Case 触发的自动化任务。
• SIEM YAML — 维护 Harness Agent 可查询的索引字段定义。
• 重启 & 运维 — 查看服务状态和日志。