Nullprivate Deploy

NullPrivate Deploy

为当前仓库执行可验证、可回滚的镜像发布。默认目标是：

• 源码：当前 NullPrivate 工作区。
• 推送镜像：registry.cn-hangzhou.aliyuncs.com/adguardprivate/adguardprivate:<tag>。
• 集群拉取镜像：registry-vpc.cn-hangzhou.aliyuncs.com/adguardprivate/adguardprivate:<tag>。
• kubeconfig：C:\Users\Administrator\.agents\skills\jqknono-k3s\references\k3s.yaml。
• namespace：adguardprivate。
• dev 工作负载：deployment/public3。
• source of truth：F:\code\ecs-manager\k3s\resources\adguardprivate.com\service-traefik\public3.yaml。

公网 registry 与 VPC registry 指向同一份阿里云镜像存储：本地只向公网地址 push，集群通过 VPC 地址 pull。

此 skill 面向当前固定 Windows 运维环境，保留上述绝对路径。执行前检查路径存在；路径失效时停止并报告，不自动搜索或复制 kubeconfig。默认直接覆盖可变的 :dev 标签，不额外创建备份标签。

When to Use

• 用户要求推送 dev、版本镜像或发布 NullPrivate。
• 用户要求更新、重启、验证或回滚 public3 Pod。
• 排查发布后的 ImagePullBackOff、rollout 超时、live digest 不一致。

不要用于 null_private 后台的 adguardprivate_master 镜像；那是另一个仓库和工作负载。

Safety Rules

• 发布是外部写操作。只有用户明确要求推送、部署、更新 Pod 或回滚时才执行变更；“检查”“看看”默认只读。
• 不提交、不打印、不复制 registry 凭据、kubeconfig 证书、Token 或其他环境变量。
• 构建命令使用 VERBOSE=0 或 VERBOSE=1。禁止使用 VERBOSE=2，因为仓库脚本会输出整个环境。
• 不修改 AdGuardHome.yaml、Secret、证书、PVC、Service、Gateway 或 Ingress，除非用户明确要求。
• 不使用 git reset --hard、git checkout -- 等方式清理工作区；镜像应包含用户当前明确要求发布的未提交修改。
• 不因 tag 相同就假设 Pod 已更新。必须核对 registry digest 与 Pod imageID。
• rollout 前记录旧 revision、Pod、imageID；失败时保留现场并给出回滚命令。
• 覆盖 :dev 前只记录旧 digest，不创建 dev-backup-* 或其他备份标签；最终报告必须说明这会限制镜像级回滚能力。
• public3 是单副本测试环境，更新期间可能短暂中断；不要同时更新其他 Deployment。

Procedure

1. Preflight

1. 读取仓库根目录 AGENTS.md 和 .vscode/tasks.json，确认当前约定没有变化。

2. 运行已存在的聚焦测试和前端生产构建。涉及过滤模块和前端时，至少执行：

   Set-Location 'F:\code\nullprivate\NullPrivate'
   go test ./internal/filtering
   make js-build VERBOSE=1

3. 查询集群，不做变更：

   $kubeconfig = 'C:\Users\Administrator\.agents\skills\jqknono-k3s\references\k3s.yaml'
   kubectl --kubeconfig $kubeconfig config current-context
   kubectl --kubeconfig $kubeconfig get deployment,pod,service -n adguardprivate -l app=public3 -o wide

4. 从 live Deployment 读取容器名、镜像、imagePullPolicy、revision；从最新 Pod 记录旧 imageID。不要猜容器名或 registry。

5. 检查 source of truth，确认镜像仍为 VPC 地址和目标 tag。若 live 与 YAML 不一致，先报告差异；需要改 YAML 时同步修改并验证，避免以后被覆盖。

6. 用 docker buildx imagetools inspect 记录推送前远端 digest。

7. 检查目标节点架构。默认 Quick dev 流程只构建 linux/amd64；若目标 Pod可能调度到 arm64，改用多架构发布，不能继续单架构镜像。

2. Build Frontend and Linux Binary

默认 dev/public3 快速发布走仓库 Quick 流程：

Set-Location 'F:\code\nullprivate\NullPrivate'
make js-build VERBOSE=1
make build-release VERBOSE=1 CHANNEL='development' ARCH='amd64' OS='linux' SIGN='0' FRONTEND_PREBUILT='1'

必须确认：

• dist\NullPrivate_linux_amd64\NullPrivate\NullPrivate 的修改时间是本次构建时间。
• 命令退出码为 0。
• 不能只看 VS Code 复合任务的第一段输出；必须确认 release 和 push 阶段分别完成。

Windows 缺少 zip 时

build-release.sh 会在任何平台构建前统一检查 zip，即使 Linux amd64 最终只生成 .tar.gz。若仅因 pieces don't fit, 'zip' not found 失败，且 Quick Dockerfile 只需要 Linux 二进制，可以使用同一底层构建脚本生成精确产物：

Set-Location 'F:\code\nullprivate\NullPrivate'
New-Item -ItemType Directory -Force '.\dist\NullPrivate_linux_amd64\NullPrivate' | Out-Null
$env:GOOS = 'linux'
$env:GOARCH = 'amd64'
$env:GOARM = ''
$env:GOMIPS = ''
$env:CHANNEL = 'development'
$env:VERSION = 'v0.0.0'
$env:RACE = '0'
$env:NEXTAPI = '0'
$env:OUT = './dist/NullPrivate_linux_amd64/NullPrivate/NullPrivate'
$env:VERBOSE = '1'
& 'C:\Program Files\Git\bin\sh.exe' './scripts/make/go-build.sh'
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
Get-Item $env:OUT | Select-Object FullName, Length, LastWriteTime

只允许在以下条件同时满足时走该 fallback：

• 前端 make js-build 已成功，仓库根目录 build/ 已更新。
• 失败原因仅为缺少 zip，不是 Go 编译、测试或前端构建错误。
• 目标只需要 Quick Dockerfile 中的 Linux 二进制，不要求完整 release 归档和 checksums。

3. Build and Push Image

默认 dev/public3：

Set-Location 'F:\code\nullprivate\NullPrivate'
docker buildx build `
  --platform linux/amd64 `
  -f docker/Dockerfile.quick `
  -t registry.cn-hangzhou.aliyuncs.com/adguardprivate/adguardprivate:dev `
  . --push

推送后执行：

docker buildx imagetools inspect registry.cn-hangzhou.aliyuncs.com/adguardprivate/adguardprivate:dev

记录新的顶层 manifest digest。新 digest 必须与推送前不同；若相同，停止 rollout 并调查是否使用了旧产物或构建上下文。

版本发布时使用用户明确给出的 tag，不自动覆盖 latest。需要多架构时使用仓库完整发布流程或分别准备 amd64/arm64 产物，不能把单架构二进制标记为多架构镜像。

4. Roll Out public3

public3.yaml 使用 VPC 镜像和 imagePullPolicy: Always。当 tag 仍为 dev 时，使用 restart 生成新的 Pod template revision：

$kubeconfig = 'C:\Users\Administrator\.agents\skills\jqknono-k3s\references\k3s.yaml'
kubectl --kubeconfig $kubeconfig rollout restart deployment/public3 -n adguardprivate
kubectl --kubeconfig $kubeconfig rollout status deployment/public3 -n adguardprivate --timeout=5m

若发布的是新 tag：

1. 先修改 F:\code\ecs-manager\k3s\resources\adguardprivate.com\service-traefik\public3.yaml 的镜像 tag。
2. 运行 server-side dry-run。
3. apply source of truth。
4. 等待 rollout。

不要只运行 kubectl set image 而不更新 YAML，否则后续 apply 会回退 live 配置。