企业官网建设流程全解析

在企业部署 AI 编程助手（Claude Code、Cursor、Codex 等）时，安全团队最关心的问题只有一个：Agent 到底做了什么，证据在哪里。agent-beacon 是跨 Agent 框架的遥测与自改进记忆层，它在本机把各 Agent 的活动归一化为 JSONL 事件流，再转发到你自己的 S3 对象存储、Splunk HEC 或 Datadog。本文是一份可直接照做的部署清单：从端点安装、三路转发配置，到验证排错，每一步都有对应命令和检查项。

1. 部署总览：一份本地日志，三个目的地

agent-beacon 的核心设计是本地优先：端点 Agent 只负责把事件写入本机 JSONL 日志，远程目的地由你现有的传输组件负责。这带来清晰的职责边界：

所有路径的"交接点"都是同一个运行时日志文件（详见 docs/log-forwarding/index.mdx）：

💡 企业批量部署一律用系统模式：日志落在共享的 root 管理路径，Fleet、Jamf 等 MDM 工具可以统一读取和策略检查。

2. 第一步：系统模式安装端点 Agent

所有转发路径都先从这里开始：

sudo /opt/beacon/bin/beacon endpoint install --system sudo /opt/beacon/bin/beacon endpoint status --system

确认Service: loaded=true running=true，且目标 Agent（如Harness: Claude Code telemetry=enabled）显示已启用。验证本机确实在写事件：

sudo /opt/beacon/bin/beacon endpoint test-event --system sudo ls -l /var/log/beacon-agent/runtime.jsonl

完整安装说明见 docs/cli/endpoint-install.mdx，本地日志查看见 docs/log-forwarding/local-jsonl.mdx。

3. 第二步：转发到 S3（数据湖归档）

S3 路径适合把 Agent 活动作为数据湖原始归档：对象为 gzip 压缩的 NDJSON，按日期分目录（s3://<bucket>/<prefix>/runtime/date=YYYY-MM-DD/...jsonl.gz），每 5 分钟或每 10 MB 上传一批。

3.1 生成 S3 转发内容包（包含 Vectoraws_s3模板、冒烟测试脚本和示例事件，见 docs/cli/s3.mdx）：

sudo /opt/beacon/bin/beacon endpoint s3 install-pack --system --output ./beacon-s3-pack

3.2 准备 AWS 侧（凭证永远留在 AWS / MDM，不进 beacon 配置）：

• 创建 IAM 用户，仅授予目标前缀的s3:PutObject（建议补s3:ListBucket供启动自检）；
• 将访问密钥通过 MDM 密钥变量下发给 Vector 服务环境；
• macOS 打包部署可参考 Fleet + S3 全流程指南 docs/guides/fleet-s3-mdm.mdx。

3.3 写入验证事件并在 S3 中确认（见 docs/log-forwarding/customer-managed.mdx）：

sudo /opt/beacon/bin/beacon endpoint s3 validate --system # 等待最长 5 分钟（分批上传），然后在有 AWS 权限的机器上： aws s3 ls "s3://<bucket>/<prefix>/runtime/" --recursive aws s3 cp "s3://<bucket>/<prefix>/runtime/date=<date>/<object>.jsonl.gz" - | gzip -dc \ | grep "Beacon endpoint S3 validation event"

能 grep 到验证事件，说明 S3 链路全通。

4. 第三步：转发到 Splunk HEC

Splunk 路径是三者中最快的——安装时直接声明目的地，beacon 内置 collector 会把 OTLP 日志、Trace、Metrics 送往你的 HTTP Event Collector（详见 docs/log-forwarding/splunk.mdx）：

beacon endpoint install \ --splunk-hec-endpoint https://splunk.example:8088/services/collector \ --splunk-hec-token "$SPLUNK_HEC_TOKEN" \ --splunk-index beacon

🔐 HEC Token 请先存入 MDM 密钥库，再在 install/repair 时传入；beacon 会把它写入本地 collector 配置以便认证。

验证三件套：

1. sudo /opt/beacon/bin/beacon endpoint status --system --json→ 确认destinations.splunk_hec.configured为true（Token 不会被打印）；
2. sudo /opt/beacon/bin/beacon endpoint wazuh validate --system→ 写入一条验证事件；
3. 在 Splunk 中搜索：

index=<your_index> sourcetype="beacon:endpoint" product="endpoint-agent" event.category="validation"

搜不到时优先检查：collector 服务是否运行、HEC 端点是否接受该 Token、TLS 设置是否匹配你的 Splunk 部署。

5. 第四步：转发到 Datadog

Datadog 路径由Datadog Agent 自定义日志采集完成——beacon 只负责生成本地 JSONL，不存储任何 Datadog API Key（详见 docs/log-forwarding/datadog.mdx）。

5.1 生成 Datadog 内容包并安装到 Agent：

sudo /opt/beacon/bin/beacon endpoint datadog install-pack --system --output ./beacon-datadog-pack sudo mkdir -p /opt/datadog-agent/etc/conf.d/beacon.d sudo cp ./beacon-datadog-pack/conf.yaml /opt/datadog-agent/etc/conf.d/beacon.d/conf.yaml sudo launchctl kickstart -k system/com.datadoghq.agent

生成的配置会 tail/var/log/beacon-agent/runtime.jsonl，并自动打上service:beacon-endpoint-agent、vendor:beacon标签。同时在datadog.yaml中确认logs_enabled: true。

5.2 检查 Agent 状态：

sudo datadog-agent status

看到beacon源Status: OK、Service: beacon-endpoint-agent，且LogsProcessed/LogsSent大于 0 即表示采集正常。

5.3 端到端验证：

sudo /opt/beacon/bin/beacon endpoint datadog validate --system

然后在 Datadog Log Explorer 中搜索service:beacon-endpoint-agent "Beacon endpoint datadog validation event"：

展开日志可见归一化字段：event.action、harness.name、prompt.text、repository、session等，可直接用于检索和告警。

⚠️ 若状态显示permission denied，说明 Agent（通常以_dd-agent运行）读不到日志文件——企业部署请用系统模式，让 Agent tail 共享路径/var/log/beacon-agent/runtime.jsonl。

6. 部署完成度检查清单

7. 常见坑速查

• 验证事件迟迟不到 S3：分批上传最长等 5 分钟；仍失败则检查转发器服务与/tmp/com.beacon.endpoint.s3-forwarder.err（Fleet 部署场景）。
• S3 启动自检报错：多为 IAM 缺少s3:ListBucket——上传仍可工作，补权限即可消除告警。
• Datadog Log Explorer 为空：确认logs_enabled: true、conf.d/beacon.d/conf.yaml存在、Agent 已重启，然后重跑datadog validate。
• Splunk 收不到：按 collector 服务 → HEC Token → TLS 顺序排查，勿在 beacon 配置里存 Token 于非受管位置。
• 换目的地时：只需替换传输组件，beacon 继续写同样的归一化日志流——这正是本地 JSONL 交接设计的价值（见 docs/concepts/vector-forwarding.mdx）。

延伸阅读

• 转发总入口（SIEM / 日志聚合 / 对象存储分类）：docs/log-forwarding/index.mdx
• Splunk HEC 完整参考：docs/log-forwarding/splunk.mdx
• Datadog 完整参考：docs/log-forwarding/datadog.mdx
• S3 命令参考：docs/cli/s3.mdx
• Fleet + S3 批量部署指南：docs/guides/fleet-s3-mdm.mdx
• 事件字段规范：docs/telemetry-schema/event-schema.mdx