快速开始:自部署控制面
有的团队要把控制面放在自己的网络里。这种情况下控制面由我们提供,部署方式和你们一起商定。试用时一台机器就够:一个控制面,一个 Agent。如果控制面要给其他人和其他 Agent 用,第 1 步改按自部署控制面做(PostgreSQL、TLS、备份)。
命令都在控制面文件的根目录执行。SDK 的命令写成 preworld-guard …,这是安装 SDK 后得到的命令。在源码目录里,uv run --frozen python -m preworld_guard … 效果相同。
1. 启动控制面
单机、用 SQLite 时,设置初始化密钥和控制面响应的主机名:
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. 开通组织和项目
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。原始值只返回这一次。
curl -X POST "$PREWORLD_GUARD_ENDPOINT/v1/tokens" \
-H "Authorization: Bearer $GUARD_OWNER_TOKEN" -H 'Content-Type: application/json' \
-d '{"role":"executor"}'| 角色 | 谁拿着 | 能做什么 |
|---|---|---|
executor | Agent(SDK 或 MCP 代理) | 拉取策略、发心跳、上报事件、申请审批 |
admin | 管策略的人 | 预演、提出和发布策略 |
reviewer | 独立审核员 | 批准或驳回候选策略 |
viewer | 审计和日志导出 | 读事件和审计,运行 siem-export |
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. 注册执行器、拉取策略
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. 包住一个工具
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 令牌预演并发布:
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":"不允许执行命令。"}]}'这样直接发布是给紧急变更用的。它会记进控制操作审计,但没有第二个人审核。正常的流程是候选、预演、独立审核、按版本发布,见发布策略。
然后各试一条正常调用和一条命中规则的调用,在事件里核对策略版本、判定结果和执行状态。