自部署控制面
自部署把控制面放在你们的网络里,由我们提供,部署方式和你们一起商定。布局是单节点的:Guard API 和 PostgreSQL 分在两个容器里,数据库只在内部网络可见,API 只绑定宿主机的回环地址,前面由宿主机上的 TLS 反向代理对外服务。它不包含负载均衡、数据库故障切换和公网防火墙规则,需要的话请自行加上。
命令都在控制面文件的根目录执行。preworld-guard 是 SDK 提供的命令(见命令行)。
密钥与主机名
在任何代码仓库之外建一个只有部署管理员可读的目录,放两个随机密钥文件:db-password 和 bootstrap-token。Linux 上 Guard 以 10001:10001 运行,所以把这两个文件的组设为 10001、权限设为 0640,目录权限设为 0700:
sudo chgrp 10001 /etc/preworld-guard/secrets/{db-password,bootstrap-token}
chmod 0640 /etc/preworld-guard/secrets/{db-password,bootstrap-token}不要把这些值写进 Compose 文件、Git 或 Agent 的容器。
启动
export GUARD_SECRETS_DIR=/etc/preworld-guard/secrets
export GUARD_ALLOWED_HOSTS=guard.example.com,127.0.0.1,localhost
export GUARD_PUBLIC_ORIGIN=https://guard.example.com
export GUARD_PORT=8765
docker compose -f deploy/control-plane.compose.yaml config --quiet
docker compose -f deploy/control-plane.compose.yaml up -d --build --wait
curl -fsS http://127.0.0.1:8765/v1/healthGUARD_SECRETS_DIR必须是绝对路径。GUARD_ALLOWED_HOSTS里保留127.0.0.1,localhost,健康检查要用。GUARD_PUBLIC_ORIGIN是大家实际访问的 HTTPS Origin(有端口就带上,不带路径)。它决定会话 Cookie 的 Secure 标志,每次写操作都会校验。控制面不信任客户端传来的X-Forwarded-Proto。/v1/health检查数据库,连不上时返回 503。配好 TLS 之后,从另一台机器经 HTTPS 再检查一次。- 正式使用时固定一个审查过的镜像 digest,用
GUARD_IMAGE指定镜像。
开通项目,然后关闭开通入口
开通入口默认关闭(GUARD_ONBOARD_ENABLED=0)。只在开通组织和项目的那一会儿打开:
GUARD_ONBOARD_ENABLED=1 docker compose -f deploy/control-plane.compose.yaml up -d --no-build --force-recreate guard
PREWORLD_GUARD_BOOTSTRAP_TOKEN="$(cat "$GUARD_SECRETS_DIR/bootstrap-token")" \
uv run --frozen python -m preworld_guard --endpoint https://guard.example.com \
onboard --organization 'Customer' --project 'support-agent'
GUARD_ONBOARD_ENABLED=0 docker compose -f deploy/control-plane.compose.yaml up -d --no-build --force-recreate guardowner 令牌只显示一次,立即存进密钥管理系统。开通入口关闭后,即使初始化密钥泄露,/v1/onboard 也只会返回 403。每调用一次都会新建一个组织和项目,再次执行前先核对已保存的项目 ID。
项目令牌
owner 令牌用来签发其他令牌,不要放进 Agent。用 POST /v1/tokens 按角色各签发一个:
| 角色 | 用途 |
|---|---|
executor | 在 Agent 里同步策略、发心跳、上报事件 |
viewer | 读取审计数据、siem-export |
reviewer | 审核候选策略 |
admin | 管理策略 |
POST /v1/tokens 只向 owner 显示一次原始值。GET /v1/tokens 只列出 ID、前缀和状态。POST /v1/token/rotate 撤销调用者自己的令牌。POST /v1/tokens/{id}/revoke 让 owner 撤销任意令牌。
项目令牌是服务身份,证明不了是哪个人在用。直接发布的接口(POST /v1/policy/publish、POST /v1/policy/dsl/publish)仍向所有者和管理员开放,留给紧急变更:它会记进控制操作审计,但没有第二个人审核。
控制台的企业账号登录
自部署的控制台用你们的 OIDC 身份提供方登录。要求 RS256 签名的令牌、带 PKCE(S256)的授权码流程、固定的 issuer 和 JWKS 地址,以及组声明。先开通项目,再写配置:
{
"project_id": "REPLACE_WITH_PROJECT_ID",
"issuer": "https://id.example.com/realms/company",
"audience": "preworld-guard-console",
"jwks_url": "https://id.example.com/realms/company/protocol/openid-connect/certs",
"authorization_endpoint": "https://id.example.com/realms/company/protocol/openid-connect/auth",
"token_endpoint": "https://id.example.com/realms/company/protocol/openid-connect/token",
"client_secret_file": "/run/secrets/oidc_client_secret",
"group_roles": {
"guard-owners": "owner",
"guard-admins": "admin",
"guard-reviewers": "reviewer",
"guard-viewers": "viewer"
}
}在身份提供方注册精确的回调地址 https://guard.example.com/v1/oidc/callback,把 oidc-client-secret 放进密钥目录,然后带上 OIDC 的覆盖文件启动:
export GUARD_OIDC_CONFIG_FILE=/etc/preworld-guard/oidc-login.json
export GUARD_PUBLIC_ORIGIN=https://guard.example.com
# secrets 目录包含 oidc-client-secret;沿用控制面 10001 组与 0640 文件权限。
docker compose -f deploy/control-plane.compose.yaml -f deploy/oidc.compose.yaml config --quiet
docker compose -f deploy/control-plane.compose.yaml -f deploy/oidc.compose.yaml up -d --wait- 各个端点都要显式配置,不做自动发现。
- 只有在已映射的组里的人才能登录。同时属于多个组的人,按所有者、管理员、审核员、只读成员的顺序取第一个。
- 账号绑定身份提供方的 issuer 和 subject,从不按邮箱合并。
- 会话最长 15 分钟,并且不超过 ID token 的有效期。
- 组的变化在下一次登录时生效。没有 SCIM,也没有全局单点登出。在身份提供方里停用某人,要等他当前的令牌和会话到期后才生效。
- 每个项目只能配置一个身份提供方。
备份、恢复与升级
定期在受控主机上备份 PostgreSQL,并在隔离环境里演练恢复:
docker compose -f deploy/control-plane.compose.yaml exec -T postgres pg_dump -U guard -Fc guard > guard.dump
docker compose -f deploy/control-plane.compose.yaml stop guard
docker compose -f deploy/control-plane.compose.yaml exec -T postgres pg_restore -U guard --clean --if-exists -d guard < guard.dump
docker compose -f deploy/control-plane.compose.yaml start guard
curl -fsS http://127.0.0.1:${GUARD_PORT:-8765}/v1/health- 备份里有策略、审计记录和令牌摘要。要加密保存,并限制谁能读。
- SDK 的事件队列在 Agent 所在的主机上,不在这个数据库里。
- 数据库迁移只往前走。已有的 PostgreSQL 数据库,只有在
PREWORLD_GUARD_MIGRATION_BACKUP_FILE指向一份升级前做的、可读的pg_dump -Fc备份时才会升级,否则控制面拒绝启动。比数据库版本旧的控制面也会拒绝启动。 - 升级前记下镜像 digest、备份和当前策略版本。升级后检查健康状态、令牌权限、策略同步、审计导出,以及一条放行和一条拒绝的动作。
这是单节点的 Compose 部署,没有无停机升级,也没有故障切换。
自部署时的 SDK
Agent 从我们提供的私有源或 wheel 安装 preworld-guard-sdk,不要从公共 PyPI 安装。固定确切的版本和 SHA-256,或者用带 #sha256= 的 wheel 地址安装。