Skip to content

快速开始:自部署控制面 ​

有的团队要把控制面放在自己的网络里。这种情况下控制面由我们提供,部署方式和你们一起商定。试用时一台机器就够:一个控制面,一个 Agent。如果控制面要给其他人和其他 Agent 用,第 1 步改按自部署控制面做(PostgreSQL、TLS、备份)。

命令都在控制面文件的根目录执行。SDK 的命令写成 preworld-guard …,这是安装 SDK 后得到的命令。在源码目录里,uv run --frozen python -m preworld_guard … 效果相同。

1. 启动控制面 ​

单机、用 SQLite 时,设置初始化密钥和控制面响应的主机名:

sh
export PREWORLD_GUARD_BOOTSTRAP_TOKEN='replace-with-a-random-value'
export PREWORLD_GUARD_ALLOWED_HOSTS='guard.example.com'
export PREWORLD_GUARD_ENDPOINT='https://guard.example.com'
export PREWORLD_GUARD_DB='/var/lib/preworld-guard/control.sqlite3'
uv run --frozen python -m guard_demo serve --host 0.0.0.0 --port 8765

初始化密钥只用来开通组织和项目,不要交给 Agent 或执行器。正式部署要放在 TLS 终止层后面,密钥放进密钥管理系统,用独立的服务账号运行。

2. 开通组织和项目 ​

sh
preworld-guard --endpoint https://guard.example.com \
  onboard \
  --bootstrap-token "$PREWORLD_GUARD_BOOTSTRAP_TOKEN" \
  --organization 'Example' \
  --project 'support-agent'

记下返回的 project.id 和 owner 的 access_token。owner 令牌用来签发其他令牌,不要放进 Agent 进程。

3. 签发项目令牌 ​

用 owner 令牌调用 POST /v1/tokens,每个角色签发一次:executor、admin、reviewer、viewer。原始值只返回这一次。

sh
curl -X POST "$PREWORLD_GUARD_ENDPOINT/v1/tokens" \
  -H "Authorization: Bearer $GUARD_OWNER_TOKEN" -H 'Content-Type: application/json' \
  -d '{"role":"executor"}'
角色谁拿着能做什么
executorAgent(SDK 或 MCP 代理)拉取策略、发心跳、上报事件、申请审批
admin管策略的人预演、提出和发布策略
reviewer独立审核员批准或驳回候选策略
viewer审计和日志导出读事件和审计,运行 siem-export
sh
export PREWORLD_GUARD_PROJECT_ID='prj_...'
export PREWORLD_GUARD_TOKEN='pwg_...'
export GUARD_ADMIN_TOKEN='pwg_...'
export GUARD_REVIEWER_TOKEN='pwg_...'

项目令牌是服务身份,证明不了是哪个人在用。动作审批只能由在控制台用具名账号登录的人处理,所以要用动作审批、要让人登录控制台,都需要配置企业账号登录,见自部署控制面。

4. 安装 SDK ​

SDK 的包名是 preworld-guard-sdk,私有分发。只从我们给你们的私有源或 wheel 安装,不要从公共 PyPI 装:那里这个名字没人注册。固定版本和哈希。见 Python SDK。

5. 注册执行器、拉取策略 ​

sh
preworld-guard \
  --endpoint https://guard.example.com \
  --project-id "$PREWORLD_GUARD_PROJECT_ID" \
  --token "$PREWORLD_GUARD_TOKEN" register --name support-agent

preworld-guard \
  --endpoint https://guard.example.com \
  --project-id "$PREWORLD_GUARD_PROJECT_ID" \
  --token "$PREWORLD_GUARD_TOKEN" policy

这一步只是验证一次接入。长驻的 Agent 改用 guard.start():它注册执行器,每 15 秒发一次心跳,并确认自己加载了哪个策略。策略缓存在 .preworld-guard/policy.json,读取时校验 SHA-256。

6. 包住一个工具 ​

python
from preworld_guard import GuardClient, GuardDenied

guard = GuardClient(
    endpoint="https://guard.example.com",
    token="pwg_...",
    project_id="prj_...",
    agent_id="support-agent",
)
guard.start(name="support-agent")

@guard.tool("search_customer")
def search_customer(customer_id: str):
    return database.search(customer_id)

try:
    search_customer("customer-42")
except GuardDenied as error:
    print(error.decision.reason_code, error.decision.message)

框架里的 Agent 和 MCP 服务,见框架适配器和 MCP 代理。

7. 先观察,再强制执行 ​

项目默认是只观察模式。先让 Agent 上报几次真实动作,再用 admin 令牌预演并发布:

sh
curl -X POST "$PREWORLD_GUARD_ENDPOINT/v1/policy/preview" \
  -H "Authorization: Bearer $GUARD_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"mode":"enforce","rules":[{"rule_id":"deny-shell","effect":"deny","resource":"shell.exec","message":"不允许执行命令。"}]}'

curl -X POST "$PREWORLD_GUARD_ENDPOINT/v1/policy/publish" \
  -H "Authorization: Bearer $GUARD_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"mode":"enforce","rules":[{"rule_id":"deny-shell","effect":"deny","resource":"shell.exec","message":"不允许执行命令。"}]}'

这样直接发布是给紧急变更用的。它会记进控制操作审计,但没有第二个人审核。正常的流程是候选、预演、独立审核、按版本发布,见发布策略。

然后各试一条正常调用和一条命中规则的调用,在事件里核对策略版本、判定结果和执行状态。

接下来 ​