Skip to content

自部署控制面 ​

自部署把控制面放在你们的网络里,由我们提供,部署方式和你们一起商定。布局是单节点的:Guard API 和 PostgreSQL 分在两个容器里,数据库只在内部网络可见,API 只绑定宿主机的回环地址,前面由宿主机上的 TLS 反向代理对外服务。它不包含负载均衡、数据库故障切换和公网防火墙规则,需要的话请自行加上。

命令都在控制面文件的根目录执行。preworld-guard 是 SDK 提供的命令(见命令行)。

密钥与主机名 ​

在任何代码仓库之外建一个只有部署管理员可读的目录,放两个随机密钥文件:db-password 和 bootstrap-token。Linux 上 Guard 以 10001:10001 运行,所以把这两个文件的组设为 10001、权限设为 0640,目录权限设为 0700:

sh
sudo chgrp 10001 /etc/preworld-guard/secrets/{db-password,bootstrap-token}
chmod 0640 /etc/preworld-guard/secrets/{db-password,bootstrap-token}

不要把这些值写进 Compose 文件、Git 或 Agent 的容器。

启动 ​

sh
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/health
  • GUARD_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)。只在开通组织和项目的那一会儿打开:

sh
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 guard

owner 令牌只显示一次,立即存进密钥管理系统。开通入口关闭后,即使初始化密钥泄露,/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 地址,以及组声明。先开通项目,再写配置:

json
{
  "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 的覆盖文件启动:

sh
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,并在隔离环境里演练恢复:

sh
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 地址安装。