自托管部署

Plystra v1.0 面向 PostgreSQL 自托管。推荐生产形态：

reverse proxy / load balancer
    -> plystra-core
        -> PostgreSQL
        -> built-in trusted system capabilities

以仓库内的 Dockerfile、docker-compose.yml、migrations 和 plystractl 检查作为 baseline。

Compose baseline

cp .env.example .env
docker compose up -d --build postgres
docker compose run --rm plystra-core plystractl migrate up
docker compose run --rm plystra-core plystractl migrate verify
docker compose up -d plystra-core

Compose 不会自动执行 migrations。启动 Core 或滚动新镜像前，需要显式 apply 并 verify migrations。

重要 Compose 变量：

变量	默认值	用途
`SERVER_PORT`	`8080`	Core 对外端口。
`DOCKER_DATABASE_URL`	Compose PostgreSQL URL	容器内连接数据库使用。
`CORS_ALLOWED_ORIGINS`	localhost 列表	显式浏览器 origins。生产模式会拒绝 wildcard CORS。
`PLYSTRA_SESSION_SECRET`	开发 placeholder	用于 HMAC opaque session token 的 secret。
`PLYSTRA_API_KEY_SECRET`	开发 placeholder	用于 HMAC API key 的 secret。生产要求独立强 secret。
`HTTP_READ_HEADER_TIMEOUT`	`5s`	防止慢速 header 读取。
`HTTP_READ_TIMEOUT`	`30s`	请求读取超时。
`HTTP_WRITE_TIMEOUT`	`60s`	响应写入超时。
`HTTP_IDLE_TIMEOUT`	`120s`	keep-alive idle timeout。
`PLYSTRA_AUTH_REGISTRATION_ENABLED`	`false`	系统已有 instance super admin 后，启用 token-protected 普通 Core 注册。
`PLYSTRA_AUTH_REGISTRATION_TOKEN`	空	普通 Core 注册共享 token。启用时使用 32+ 字符强值。
`PLYSTRA_BOOTSTRAP_REGISTRATION_ENABLED`	`false`	仅在还没有 instance super admin 时启用受保护首个 super admin 注册路径。
`PLYSTRA_BOOTSTRAP_REGISTRATION_TOKEN`	空	独立首个 super admin bootstrap 强 token。
`PLYSTRA_AUTH_PUBLIC_USER_REGISTRATION_ENABLED`	`false`	启用更窄的公开 user-only Core 注册；只创建 User。
`DATA_CONSOLE_ENABLED`	`false`	默认关闭 preview data routes。
`METRICS_ENABLED`	`false`	默认关闭 `/metrics`。

本地开发的 .env.example 使用显式 localhost CORS 值。

System Capabilities

官方 system capabilities 会编译进 plystrad binary，并由 kernel 在启动时加载：

audit.explainable
identity.business
resource.registry
authorization.resource
admin.control_plane

它们通过 internal/kernel/contracts 注册 services、routes、migration ownership metadata 和 lifecycle health。不要把这个机制用于第三方 runtime install、hot unload、marketplace 替换 authz/audit/identity、sidecar loading 或 Go ABI plugin。

迁移流程

启动可信 API 前必须应用迁移：

go run entgo.io/ent/cmd/ent generate ./ent/schema
go run ./cmd/plystractl migrate up
go run ./cmd/plystractl migrate verify
go run ./cmd/plystractl ent check
go run ./cmd/plystractl doctor

生产升级必须使用版本化 migrations。不要把 Ent auto migration 当成生产升级机制。

Runtime database access 使用 Ent。生产 schema 变更通过 plystra/migrations/ 下的 versioned Atlas-style SQL 文件表示，并记录在 schema_migrations。System capability migration ownership 通过 kernel 注册，但 release migration 仍通过同一套 Atlas-style migration flow 执行。

启动 Core

go run ./cmd/plystrad

或使用 Compose：

docker compose up -d plystra-core

Core 暴露：

GET /api/v1/health
GET /api/v1/ready
GET /api/v1/version

readiness endpoint 会检查数据库连接、预期 migration/schema 状态和 required system capability readiness。

生产必填配置

当 SERVER_MODE=production 时，启动前会验证：

配置	生产规则
`DATABASE_URL` 或 `PLYSTRA_DATABASE_URL`	必填；不能使用默认 `plystra:plystra` 凭据。
`PLYSTRA_SESSION_SECRET`	至少 32 字符，不能是默认 placeholder。
`PLYSTRA_API_KEY_SECRET`	至少 32 字符，不能是默认 placeholder，且必须与 session secret 不同。
`CORS_ALLOWED_ORIGINS`	必填；不能包含 `*`。
`SERVER_PUBLIC_URL` 或 `PLYSTRA_SERVER_PUBLIC_URL`	必填；不能指向 localhost。

当前 runtime 使用 opaque bearer token，存储 HMAC token hash，不签发 JWT claims。

第一个 Instance Super Admin

Core 管理 API 使用和业务授权一致的 User/session 体系。第一个管理员是一个 AdminGrant：

level = instance_super_admin
permission_key = *

Migrations 不会自动创建该 grant。迁移完成后、服务暴露前执行：

go run ./cmd/plystractl admin bootstrap-super-admin --user-id <existing_user_id>

如果系统里已经存在 active instance super admin，这个命令会拒绝执行。完成 bootstrap 后，用该用户登录，再通过 /api/v1/admin/grants 创建更多管理员。

Complete Auth Plugin

Core 有意只保留最小认证面：受保护注册、密码登录、refresh/logout 和 actor context。公开注册、email verification code、magic link 和邮件 provider 集成位于独立 Complete Auth plugin repo。

从父级 workspace 构建插件，这样 Go module replacement 能找到独立 email-contracts 仓库：

cd plystra
docker build -f plugin-auth-complete/Dockerfile -t plystra-auth-complete .

启动插件前，把 Complete Auth plugin SQL migrations 应用到同一个 PostgreSQL 数据库。插件把非敏感运行时设置保存在 plugin_auth_settings，包括 public registration、delivery mode、capability URL、sender address、redirect allowlist、TTL、rate limit、max body size 和 trusted proxy CIDR。Secrets 仍然使用环境变量或 secret manager。

生产邮件发送必须配置：

email_delivery_mode = "capability"
email_capability_url = "https://..."
email_from_address = "[email protected]"

email_capability_url 必须实现独立 email delivery contract。官方 provider plugin repo 包括 SMTP 和 Cloudflare Email Sending。

Backend OS Alpha Templates

如需可审计的一键初始化 scaffold，可以从官方模板生成应用目录：

go run ./cmd/plystractl templates create --template auth-ready-saas --name "Acme SaaS" --out ./acme-saas

生成目录包含 docker-compose.yml、.env.example、template manifest、install explanation 和 README。它不会写入真实 secrets，不会自动执行 migrations，也不会创建第一个 instance super admin。先审阅生成文件，设置生产 secrets，再按生成的 README 启动和验证。

反向代理与客户端 IP

只有配置 TRUSTED_PROXIES 时，Plystra 才信任 forwarded IP headers。否则 request IP metadata 来自 RemoteAddr。

只为你自己控制的反向代理配置它：

TRUSTED_PROXIES=127.0.0.1,10.0.0.0/8

审计配置

生产环境建议保持：

AUDIT_WRITE_MODE=always
TRACE_VERSION=1.0

授权决策和 Core management mutations 都会写入 audit trace。AuditLog 是 append-only，需要纳入备份和保留策略。

备份与升级 checklist

升级前：

阅读 release notes。
运行 plystractl doctor。
备份 PostgreSQL。
必要时停止或静默写流量。
应用 migrations。
运行 migrate verify、ent check、doctor。
Smoke test health、ready、version、authz/check、authz/explain、Resource Registry、AuditLog 查询和 /api/v1/capabilities。

最低备份命令：

pg_dump "$DATABASE_URL" > plystra-backup.sql