pds

PDS 技能用于在 joelclaw k8s 集群中操作 AT Protocol 个人数据服务器（Personal Data Server）。

用途

该技能适用于检查 PDS 健康状态、读取或写入 dev.joelclaw.* 记录、恢复服务等场景。

当前事实

Helm 发布：bluesky-pds
命名空间：joelclaw
Values 文件：infra/pds/values.yaml
健康检查 URL：http://localhost:9627/xrpc/_health
主机端口：9627
服务 nodePort：3000
句柄：joel.pds.panda.tail7af24.ts.net
当前 DID：did:plc:5w6ablyvahugobsj7n57yjmm

CLI 界面

可用命令包括：

joelclaw pds
joelclaw pds health
joelclaw pds describe
joelclaw pds collections
joelclaw pds records dev.joelclaw.system.log --limit 5
joelclaw pds write dev.joelclaw.system.log --data '{"action":"verify","tool":"pds","detail":"manual check"}'
joelclaw pds delete dev.joelclaw.system.log <rkey>
joelclaw pds session --refresh

语义说明：

会话缓存位于 ~/.joelclaw/pds-session.json
CLI 和主机 system-bus 客户端在 createSession 之前从 pds_joel_did 解析仓库句柄
重建后原始 DID 登录不可靠；句柄登录可用
写入会自动添加 $type 和 createdAt

重建后恢复

重建后的集群即使 Pod 健康，也可能带回一个空的 PDS。恢复服务需要两步：

1）重新创建 secrets 和 Helm 发布

JWT_SECRET=$(secrets lease pds_jwt_secret --ttl 10m)
ADMIN_PASSWORD=$(secrets lease pds_admin_password --ttl 10m)
PLC_ROTATION_KEY=$(secrets lease pds_plc_rotation_key --ttl 10m)

kubectl create secret generic bluesky-pds-secrets \
  -n joelclaw \
  --from-literal=jwtSecret="$JWT_SECRET" \
  --from-literal=adminPassword="$ADMIN_PASSWORD" \
  --from-literal=plcRotationKey="$PLC_ROTATION_KEY" \
  --from-literal=emailSmtpUrl='' \
  --dry-run=client -o yaml | kubectl apply -f -

helm upgrade --install bluesky-pds nerkho/bluesky-pds \
  -n joelclaw \
  -f ~/Code/joelhooks/joelclaw/infra/pds/values.yaml

kubectl patch svc bluesky-pds -n joelclaw --type='json' \
  -p='[{"op":"replace","path":"/spec/ports/0/nodePort","value":3000}]'

kubectl rollout status deployment/bluesky-pds -n joelclaw
curl -fsS http://localhost:9627/xrpc/_health

2）如果 PVC 被清除，重新创建 Joel 的账户

ADMIN_PASSWORD=$(secrets lease pds_admin_password --ttl 10m)
JOEL_PASSWORD=$(secrets lease pds_joel_password --ttl 10m)

INVITE_CODE=$(curl -fsS -u "admin:${ADMIN_PASSWORD}" \
  -H 'content-type: application/json' \
  -d '{"useCount":1}' \
  http://localhost:9627/xrpc/com.atproto.server.createInviteCode | jq -r '.code')

curl -fsS -X POST http://localhost:9627/xrpc/com.atproto.server.createAccount \
  -H 'content-type: application/json' \
  -d "$(jq -nc \
    --arg email 'joelhooks@gmail.com' \
    --arg handle 'joel.pds.panda.tail7af24.ts.net' \
    --arg password "$JOEL_PASSWORD" \
    --arg inviteCode "$INVITE_CODE" \
    '{email:$email,handle:$handle,password:$password,inviteCode:$inviteCode}')"

然后更新 pds_joel_did 为 createAccount 返回的新 DID。如果跳过这一步，主机双写路径将针对一个已失效的仓库进行认证。

快速检查

curl -fsS http://localhost:9627/xrpc/_health
joelclaw pds describe
joelclaw pds collections
kubectl get deploy,svc,pods,pvc -n joelclaw | rg 'bluesky-pds|NAME'
kubectl logs -n joelclaw -l app.kubernetes.io/name=bluesky-pds --tail=50

注意事项

nodePort 必须保持为 3000。主机暴露端口是 9627，但服务仍指向容器侧端口 3000。
重建可能清除 PVC 并静默使旧 DID 失效。
createSession 在重建后的 PDS 上对句柄有效，但拒绝原始 DID 登录。
describeRepo 是从存储的 DID 恢复当前句柄的真相来源。

关键文件

infra/pds/values.yaml
packages/cli/src/commands/pds.ts
packages/system-bus/src/lib/pds.ts
docs/deploy.md
Vault/docs/decisions/0044-pds-private-first-with-bento-bridge.md