Runtime Configuration

Perago runtime configuration 是 worker-local 配置。它控制本机 workspace 目录、日志目录、worker id、Conductor 连接和 LakeFS 连接；这些值不属于 Conductor task input/output，也不会写入生成的 TaskDef JSON。

配置由 load_runtime_config() 统一读取。perago check、perago extract 和 perago start 都会在加载 task module 前执行同一套配置加载与校验。

配置来源和优先级

Perago 会读取当前工作目录下的 .env，再用真实进程环境变量覆盖同名值：

.env values < process environment values

.env 只填补缺失值。部署系统、shell 或 supervisor 注入的进程环境变量拥有更高优先级。

.env 支持简单的 KEY=value、export KEY=value、单引号和双引号包裹的值。空行、注释行和没有 = 的行会被忽略。

最小本地示例

CONDUCTOR_SERVER_URL=http://localhost:8080/api

# Required only when starting workspace tasks.
# LAKECTL_SERVER_ENDPOINT_URL=http://localhost:8000
# LAKECTL_CREDENTIALS_ACCESS_KEY_ID=replace-with-real-access-key
# LAKECTL_CREDENTIALS_SECRET_ACCESS_KEY=replace-with-real-secret-key

PERAGO_WORKSPACE_ROOT=/var/tmp/perago/workspaces
PERAGO_LOG_ROOT=/var/tmp/perago/logs
PERAGO_LOG_FILE_MAX_SIZE=100MB
PERAGO_LOG_RETENTION=30d
PERAGO_WORKER_ID_PREFIX=peragoLocalWorker
PERAGO_FAILURE_REASON_MAX_LENGTH=500
PERAGO_WORKSPACE_GC_TTL=24h
PERAGO_WORKSPACE_GC_INTERVAL=1h
# Optional; unset by default.
PERAGO_SHUTDOWN_FORCE_KILL_AFTER=30s

replace-me 属于占位值。Perago 看到未替换的连接密钥占位值时会拒绝启动。workspace-free task 不需要 LakeFS 连接变量；不要为了启动 workspace-free worker 配置占位 LakeFS 值。

变量表

变量	Required	默认值	说明
PERAGO_WORKSPACE_ROOT	optional	平台临时目录下的 perago/workspaces	attempt-local workspace 根目录。必须是 worker 主机文件系统路径，LakeFS object path 不适用。一个 running supervisor 会独占一个 root。
PERAGO_LOG_ROOT	optional	平台临时目录下的 perago/logs	worker JSONL 日志根目录。
PERAGO_LOG_FILE_MAX_SIZE	optional	100MB	单个日志文件 rotation 阈值。接受正数加 KB、MB 或 GB，例如 512KB、100MB、1.5GB。裸数字非法。
PERAGO_LOG_RETENTION	optional	30d	日志保留天数。接受正整数加 d，例如 7d 或 30d。
PERAGO_WORKER_ID_PREFIX	optional	从 module target 删除非字母数字字符后派生	supervisor 为子进程生成 PERAGO_WORKER_ID 的前缀。显式配置时只能包含 ASCII 字母和数字。
PERAGO_WORKER_ID	generated / debug-only	supervisor 生成；非 supervisor 进程退回到 module target 加 pid	worker process 身份。perago start -j 会为每个 child slot 写入该值；用户一般不应在 .env 中配置。
PERAGO_FAILURE_REASON_MAX_LENGTH	optional	500	写入 Conductor reasonForIncompletion 的最大字符数。只接受正整数；超长 failure reason 会截断并记录截断元数据到 worker 日志。
PERAGO_WORKSPACE_GC_TTL	optional	24h	supervisor workspace GC 删除 abandoned attempt workspace 前等待的最小年龄。接受正整数加 s、m、h 或 d。仍属于活跃 executor owner 的 workspace 不会被周期 GC 删除。
PERAGO_WORKSPACE_GC_INTERVAL	optional	1h	supervisor 后台 workspace GC loop 的运行间隔。接受正整数加 s、m、h 或 d。
PERAGO_SHUTDOWN_FORCE_KILL_AFTER	optional	unset	shutdown drain 的可选强制 kill deadline。未配置时 Perago 不调用 process.kill()；配置后接受正整数加 s、m、h 或 d，例如 30s。
CONDUCTOR_SERVER_URL	required for perago start	无	Conductor API endpoint。perago check 和 perago extract 可在未配置时运行并报告 not configured。
LAKECTL_SERVER_ENDPOINT_URL	required for workspace-task perago start	无	LakeFS endpoint。LakeFS 三个变量必须同时配置或同时省略；workspace-free perago start 不需要 LakeFS。
LAKECTL_CREDENTIALS_ACCESS_KEY_ID	required for workspace-task perago start	无	LakeFS access key id。
LAKECTL_CREDENTIALS_SECRET_ACCESS_KEY	required for workspace-task perago start	无	LakeFS secret access key。

Perago 目前只解析 CONDUCTOR_SERVER_URL 作为 Conductor runtime config。Conductor auth key/secret 可以由底层 SDK 或部署环境使用；Perago RuntimeConfig 暂不建模这两个字段。

本地目录校验

默认情况下，load_runtime_config() 会探测 PERAGO_WORKSPACE_ROOT 和 PERAGO_LOG_ROOT 是否可创建、可写。探测会在目标根目录下创建临时目录和 write-test 文件，再立即删除。

perago start 会在 PERAGO_WORKSPACE_ROOT 下创建 .perago-supervisor.lock，并写入当前 supervisor pid。该锁表达部署边界：一个 supervisor 独占一个 workspace root，不允许两个 supervisor 同时指向同一个 root。如果锁内 pid 仍存活，新的 supervisor 会拒绝启动；如果上次 supervisor 或 host 崩溃留下的 pid 已不存在，启动时会清理旧锁并重新加锁。正常退出时 supervisor 会释放自己持有的锁。

perago check 因此可以在不连接 Conductor 或 LakeFS 的情况下验证本机目录配置：

perago check app.workers.features_build

成功输出会包含解析后的目录和连接配置状态：

ok: features.build
workspace_root: /var/tmp/perago/workspaces
log_root: /var/tmp/perago/logs
worker_id_prefix: peragoLocalWorker
conductor: configured
lakefs: configured

目录探测失败会抛出 RuntimeConfigError，错误文本包含不可写路径和底层 OSError。

Worker id 规则

PERAGO_WORKER_ID_PREFIX 是用户可配置的碰撞隔离旋钮。显式配置时，值必须非空并且只包含 A-Z、a-z、0-9：

PERAGO_WORKER_ID_PREFIX=prodAFeaturesBuild

perago start -j 2 app.workers.features_build 会派生：

PERAGO_WORKER_ID=prodAFeaturesBuild0001
PERAGO_WORKER_ID=prodAFeaturesBuild0002

如果没有显式配置前缀，Perago 会从 module target 派生默认前缀。例如 app.workers.features_build 会变成 appworkersfeaturesbuild。显式配置非法前缀不会被自动修正：

PERAGO_WORKER_ID_PREFIX=prod-a-features-build

会失败并报告：

PERAGO_WORKER_ID_PREFIX must contain only ASCII letters and digits

PERAGO_WORKER_ID 是进程身份。task attempt id、logical task key 和 workspace publication key 使用各自的独立字段。supervisor 管理的 worker 会由 supervisor 写入该值；只有非 supervisor 本地调试进程才会使用用户提供的 PERAGO_WORKER_ID 或 pid fallback。

命令差异

perago check 会验证配置、task module 和生成 TaskDef 的基本结构，且不连接 Conductor 或 LakeFS。

perago extract 会验证配置和 task module，然后写出 TaskDef JSON。它同样不要求 Conductor 和 LakeFS 必须已经配置完成。

perago start 会额外要求：

• CONDUCTOR_SERVER_URL 已配置。

• workspace task 需要 LakeFS endpoint、access key id 和 secret access key 已完整配置；workspace-free task 不需要 LakeFS 连接变量。

• Conductor 中已经注册了对应 TaskDef。

推荐流程是先运行 perago check，再运行 perago extract 并注册 TaskDef，最后启动 worker。