diff --git a/deploy/ecosystem.config.cjs b/deploy/ecosystem.config.cjs index 25283b8..97206ea 100644 --- a/deploy/ecosystem.config.cjs +++ b/deploy/ecosystem.config.cjs @@ -16,16 +16,5 @@ module.exports = { max_restarts: 10, time: true, }, - { - name: "personal-brand-admin-static", - cwd: path.join(root, "current"), - script: "deploy/static-server.mjs", - interpreter: process.execPath, - env: { NODE_ENV: "production", ADMIN_STATIC_PORT: "3010" }, - autorestart: true, - restart_delay: 2000, - max_restarts: 10, - time: true, - }, ], }; diff --git a/deploy/install-release.mjs b/deploy/install-release.mjs index 9e24633..7b2b500 100644 --- a/deploy/install-release.mjs +++ b/deploy/install-release.mjs @@ -42,8 +42,16 @@ if (!path.isAbsolute(process.env.LOCAL_MEDIA_ROOT)) throw new Error("LOCAL_MEDIA_ROOT must be absolute"); if (process.env.API_PREFIX) throw new Error("API_PREFIX must be empty when Traefik strips /api"); const databaseUrl = new URL(process.env.DATABASE_URL); -if (!["127.0.0.1", "localhost"].includes(databaseUrl.hostname)) { - throw new Error("DATABASE_URL must use the loopback-published PostgreSQL port"); +const privateDatabaseHost = /^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[0-1])\.)/.test( + databaseUrl.hostname, +); +if ( + !["127.0.0.1", "localhost"].includes(databaseUrl.hostname) && + !(privateDatabaseHost && process.env.ALLOW_PRIVATE_DATABASE_HOST === "true") +) { + throw new Error( + "DATABASE_URL must use loopback or explicitly approved private Docker networking", + ); } const traefikDirectory = process.env.TRAEFIK_DYNAMIC_DIR ?? "/home/ubuntu/traefik/dynamic"; const traefikGateway = process.env.TRAEFIK_DOCKER_GATEWAY ?? "172.21.0.1"; @@ -52,12 +60,55 @@ if (!/^[a-zA-Z0-9.-]+$/.test(traefikHost) || !/^[a-zA-Z0-9.:-]+$/.test(traefikGa throw new Error("Invalid Traefik host or gateway setting"); } const routeFile = path.join(traefikDirectory, "personal-brand-managed.yml"); +const adminServiceName = "personal-brand-admin-static.service"; +const adminServiceDirectory = path.join( + process.env.XDG_CONFIG_HOME ?? path.join(process.env.HOME ?? "/home/ubuntu", ".config"), + "systemd/user", +); +const adminServiceFile = path.join(adminServiceDirectory, adminServiceName); function run(command, args, cwd = root) { const result = spawnSync(command, args, { cwd, stdio: "inherit", env: process.env }); if (result.status !== 0) throw new Error(command + " failed with exit " + result.status); } +async function installAdminService(release) { + const stopped = spawnSync("systemctl", ["--user", "stop", adminServiceName], { + stdio: "ignore", + env: process.env, + }); + if (stopped.status !== 0 && stopped.status !== 5) { + throw new Error("Could not stop the previous Admin systemd unit"); + } + await mkdir(adminServiceDirectory, { recursive: true }); + await writeFile( + adminServiceFile, + `[Unit]\nDescription=Personal Brand Admin static server\nAfter=network-online.target\n\n[Service]\nType=simple\nWorkingDirectory=${release}\nEnvironment=NODE_ENV=production\nEnvironment=ADMIN_STATIC_PORT=${process.env.ADMIN_STATIC_PORT ?? "3010"}\nEnvironment=ADMIN_STATIC_ROOT=${release}/apps/admin/dist\nExecStart=${process.execPath} ${release}/deploy/static-server.mjs\nRestart=always\nRestartSec=2\n\n[Install]\nWantedBy=default.target\n`, + { mode: 0o644 }, + ); + run("systemctl", ["--user", "daemon-reload"]); + run("systemctl", ["--user", "enable", "--now", adminServiceName]); + run("systemctl", ["--user", "restart", adminServiceName]); +} + +function verifyTraefikAdmin() { + const result = spawnSync( + "docker", + [ + "exec", + "traefik", + "wget", + "-qO", + "/dev/null", + "-T", + "5", + `http://${traefikGateway}:${process.env.ADMIN_STATIC_PORT ?? "3010"}/admin/`, + ], + { stdio: "inherit", env: process.env }, + ); + if (result.status !== 0) throw new Error("Traefik cannot reach Admin static service"); +} + async function switchCurrent(target) { const temporary = current + ".next-" + process.pid; await symlink(target, temporary); @@ -173,22 +224,23 @@ async function writeTraefikRoute() { async function waitForPublicRelease(release) { const verifier = path.join(release, "scripts/deploy/verify-public-release.mjs"); - for (let attempt = 0; attempt < 12; attempt++) { + for (let attempt = 0; attempt < 4; attempt++) { const result = spawnSync(process.execPath, [verifier, release], { cwd: release, encoding: "utf8", env: process.env, - timeout: 30000, + timeout: 45000, }); if (result.status === 0) { process.stdout.write(result.stdout); return; } - if (attempt === 11) { + if (attempt === 3) { process.stderr.write(result.stderr ?? ""); + process.stdout.write(result.stdout ?? ""); throw new Error("Public release verification failed"); } - await new Promise((resolve) => setTimeout(resolve, 5000)); + await new Promise((resolve) => setTimeout(resolve, 3000)); } } @@ -260,12 +312,14 @@ try { await switchCurrent(release); switched = true; run("pm2", ["startOrRestart", path.join(release, "deploy/ecosystem.config.cjs"), "--update-env"]); + await installAdminService(release); await waitForHealth(); const staticResponse = await fetch( "http://127.0.0.1:" + (process.env.ADMIN_STATIC_PORT ?? "3010") + "/admin/", { signal: AbortSignal.timeout(5000) }, ); if (!staticResponse.ok) throw new Error("Admin static health check failed"); + verifyTraefikAdmin(); await writeTraefikRoute(); routeUpdated = true; if (!process.env.PUBLIC_BASE_URL) @@ -281,6 +335,7 @@ try { } if (switched) { await switchCurrent(previous); + await installAdminService(previous); run("pm2", [ "startOrRestart", path.join(source, "deploy/ecosystem.config.cjs"), diff --git a/docs/deployment.md b/docs/deployment.md index e2879b7..a42507c 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -6,11 +6,23 @@ API 默认监听 `http://localhost:3001`,管理后台默认监听 `http://loca ## 生产架构 -生产环境只使用 Docker Compose 运行 PostgreSQL;API 和 Admin 运行在 VPS 宿主机上。API 由 Node.js 24 + PM2 运行在 `3001`,Admin 静态服务运行在 `3010`,Traefik file provider 负责路由。用户媒体目录位于发布目录之外,发布时只补充缺失的种子图片,不覆盖上传文件。 +生产环境只使用 Docker Compose 运行 PostgreSQL;API 和 Admin 运行在 VPS 宿主机上。API 由 Node.js 24 + PM2 运行在 `3001`,Admin 静态服务由 user-level `systemd` 运行在 `3010`,Traefik file provider 负责路由。Traefik 所在 Docker 网段必须允许访问宿主机 `3010`,但不需要向公网开放该端口。用户媒体目录位于发布目录之外,发布时只补充缺失的种子图片,不覆盖上传文件。 每次发布先创建 PostgreSQL `pg_dump` 备份,再执行 Prisma migration 和公网健康检查;检查失败时恢复应用版本和 Traefik 路由。数据库 migration 不自动回滚,必须使用备份恢复或人工处理。 -`docker-compose.prod.yml` 只负责 PostgreSQL,不再定义 API、Admin 或业务镜像。 +`docker-compose.prod.yml` 只负责 PostgreSQL,不再定义 API、Admin 或业务镜像。Gitea 用于保存源码、发布包和 SHA-256 校验文件;生产机只安装经过校验的发布包,不在 VPS 上临时拉取源码并构建。 + +日常发布只执行一条命令: + +```bash +pnpm deploy:release +``` + +命令会自动构建 Admin 和 API、生成带 manifest 的发布包、生成 SHA-256、上传到 `DEPLOY_TARGET`(默认 `oracle_arm`)、在 VPS 校验并安装、备份数据库、执行 migration、切换服务和 Traefik,最后检查 Admin、模板预览、API 和媒体。需要更换目标或域名时通过环境变量配置: + +```bash +DEPLOY_TARGET=oracle_arm PUBLIC_BASE_URL=https://wechat.app.que01.top pnpm deploy:release +``` ## Nginx 反向代理 @@ -81,7 +93,7 @@ pnpm deploy:package pnpm deploy:package ``` -脚本生成带完整文件清单和 SHA-256 的版本目录及归档,归档旁边会生成 `.sha256` 文件。上传到 VPS 后由 `deploy/install-release.mjs` 复用 pnpm store 安装依赖、备份数据库、执行迁移、切换 PM2 和 Traefik 路由,并运行公网验证。 +脚本生成带完整文件清单和 SHA-256 的版本目录及归档,归档旁边会生成 `.sha256` 文件。上传到 VPS 后由 `deploy/install-release.mjs` 复用 pnpm store 安装依赖、备份数据库、执行迁移、切换 PM2、systemd 和 Traefik 路由,并运行公网验证。切流前必须通过 Traefik 容器访问 Admin 上游的检查。 首次部署可以执行一次 `pnpm db:seed` 创建管理员与演示品牌。已有生产环境禁止重复执行种子命令;模板示例内容只能由管理员在后台对指定品牌显式导入,不能把示例数据扩展到全局种子。 diff --git a/package.json b/package.json index 81d4f0b..187c3b2 100644 --- a/package.json +++ b/package.json @@ -29,6 +29,7 @@ "preview:templates": "pnpm --filter @personal-brand/taro dev:preview", "deploy:verify": "node scripts/deploy/verify-release.mjs", "deploy:package": "node scripts/deploy/package-release.mjs", + "deploy:release": "node scripts/deploy/publish-release.mjs", "deploy:images": "node scripts/deploy/export-images.mjs", "test:deploy-verify": "node --test scripts/deploy/verify-release.test.mjs", "test:deploy": "node --test scripts/deploy/*.test.mjs deploy/*.test.mjs", diff --git a/scripts/deploy/publish-release.mjs b/scripts/deploy/publish-release.mjs new file mode 100644 index 0000000..26e4df5 --- /dev/null +++ b/scripts/deploy/publish-release.mjs @@ -0,0 +1,83 @@ +import { access } from "node:fs/promises"; +import path from "node:path"; +import { spawnSync } from "node:child_process"; +import { fileURLToPath } from "node:url"; + +const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../.."); +const target = process.env.DEPLOY_TARGET ?? "oracle_arm"; +const remoteRoot = process.env.DEPLOY_ROOT ?? "/home/ubuntu/persional-brand"; +const publicBaseUrl = process.env.PUBLIC_BASE_URL ?? "https://wechat.app.que01.top"; +const timestamp = new Date().toISOString().replace(/\D/g, "").slice(0, 14); +const git = spawnSync("git", ["rev-parse", "--short=12", "HEAD"], { + cwd: root, + encoding: "utf8", +}); +if (git.status !== 0) throw new Error("Cannot determine source revision"); +const version = process.env.RELEASE_VERSION ?? timestamp + "-" + git.stdout.trim(); +const releasePrefix = "personal-brand-" + version; +const archiveName = releasePrefix + ".tar.gz"; +const archive = path.join(root, "dist/releases", archiveName); + +function run(command, args, options = {}) { + const stdio = options.input === undefined ? "inherit" : ["pipe", "inherit", "inherit"]; + const result = spawnSync(command, args, { cwd: root, stdio, ...options }); + if (result.status !== 0) throw new Error(command + " failed with exit " + result.status); +} + +if (!/^[a-zA-Z0-9_.@:-]+$/.test(target)) throw new Error("Invalid deployment SSH target"); +if (!/^\/[a-zA-Z0-9_./-]+$/.test(remoteRoot)) throw new Error("Invalid deployment root"); +const publicUrl = new URL(publicBaseUrl); +if (publicUrl.protocol !== "https:") throw new Error("PUBLIC_BASE_URL must use HTTPS"); + +const packageResult = spawnSync("pnpm", ["deploy:package"], { + cwd: root, + stdio: "inherit", + env: { ...process.env, RELEASE_VERSION: version }, +}); +if (packageResult.status !== 0) process.exit(packageResult.status ?? 1); + +await access(archive); +await access(archive + ".sha256"); +run("scp", [archive, archive + ".sha256", target + ":/tmp/"]); + +const remoteScript = [ + "set -eu", + 'export NVM_DIR="$HOME/.nvm"', + '. "$NVM_DIR/nvm.sh"', + 'release="/tmp/' + releasePrefix + '"', + 'rm -rf "$release"', + 'mkdir -p "$release"', + "cd /tmp", + 'sha256sum -c "' + releasePrefix + '.tar.gz.sha256"', + 'tar -xzf "' + archiveName + '" -C "$release"', + "pnpm_bin=$(find \"$HOME/.cache/pnpm/dlx\" -path '*/pnpm@9.15.0/node_modules/pnpm/bin/pnpm.cjs' -print -quit)", + 'test -n "$pnpm_bin"', + "mkdir -p /tmp/pnpm-9.15-bin", + 'ln -sf "$pnpm_bin" /tmp/pnpm-9.15-bin/pnpm', + "export PATH=/tmp/pnpm-9.15-bin:$PATH", + 'export DEPLOY_ROOT="' + remoteRoot + '"', + 'export PUBLIC_BASE_URL="' + publicBaseUrl + '"', + "export TRAEFIK_DYNAMIC_DIR=/home/ubuntu/traefik/dynamic", + 'cd "$release"', + "node deploy/install-release.mjs .", +].join("; "); + +run("ssh", [target, "bash -s"], { input: remoteScript + "\n" }); + +const checks = ["/admin/", "/template-preview/", "/api/health", "/media/seed/food-package-02.jpg"]; +for (const route of checks) { + run("curl", [ + "--fail", + "--silent", + "--show-error", + "--max-time", + "10", + "-o", + "/dev/null", + "-w", + route + " %{http_code}\\n", + publicBaseUrl + route, + ]); +} + +console.log("release published: " + version); diff --git a/scripts/deploy/verify-public-release.mjs b/scripts/deploy/verify-public-release.mjs index 875a3ab..7c111f5 100644 --- a/scripts/deploy/verify-public-release.mjs +++ b/scripts/deploy/verify-public-release.mjs @@ -21,21 +21,24 @@ const contentTypes = new Map([ ]); async function checkResource(url, expectedType, label) { - const response = await fetch(url); + const response = await fetch(url, { signal: AbortSignal.timeout(10000) }); const contentType = response.headers.get("content-type") ?? ""; assert.equal(response.status, 200, label + " returned " + response.status); assert.ok(contentType.includes(expectedType), label + " has content type " + contentType); + await response.body?.cancel(); } async function checkHtmlAssets(relativeEntry, localPath, publicPath) { const html = await readFile(localPath, "utf8"); + const checks = []; for (const match of html.matchAll(/(?:src|href)=["']([^"']+)["']/g)) { const asset = match[1]; if (!/\.(?:js|css)(?:[?#]|$)/.test(asset)) continue; const url = new URL(asset, baseUrl + publicPath); const expectedType = /\.css(?:[?#]|$)/.test(url.pathname) ? "text/css" : "javascript"; - await checkResource(url, expectedType, relativeEntry + " -> " + asset); + checks.push(checkResource(url, expectedType, relativeEntry + " -> " + asset)); } + await Promise.all(checks); } async function listFiles(directory, prefix = "") { @@ -49,7 +52,9 @@ async function listFiles(directory, prefix = "") { return files; } -const apiHealthResponse = await fetch(baseUrl + "/api/health"); +const apiHealthResponse = await fetch(baseUrl + "/api/health", { + signal: AbortSignal.timeout(10000), +}); assert.equal(apiHealthResponse.status, 200, "public API health check failed"); assert.match(apiHealthResponse.headers.get("content-type") ?? "", /application\/json/); assert.equal((await apiHealthResponse.json()).status, "ok"); @@ -67,23 +72,27 @@ for (const [entry, localFile, publicPath] of [ } const assetRoot = path.join(root, "apps/admin/dist/assets"); -for (const asset of await listFiles(assetRoot)) { - const extension = path.extname(asset).toLowerCase(); - const expectedType = contentTypes.get(extension); - if (!expectedType) continue; - await checkResource( - baseUrl + "/assets/" + asset.split("/").map(encodeURIComponent).join("/"), - expectedType, - "static asset " + asset, - ); -} +await Promise.all( + (await listFiles(assetRoot)).map(async (asset) => { + const extension = path.extname(asset).toLowerCase(); + const expectedType = contentTypes.get(extension); + if (!expectedType) return; + await checkResource( + baseUrl + "/assets/" + asset.split("/").map(encodeURIComponent).join("/"), + expectedType, + "static asset " + asset, + ); + }), +); -for (const entry of await readdir(path.join(root, "seed-media"))) { - await checkResource( - baseUrl + "/media/seed/" + encodeURIComponent(entry), - "image/jpeg", - "seed media " + entry, - ); -} +await Promise.all( + (await readdir(path.join(root, "seed-media"))).map((entry) => + checkResource( + baseUrl + "/media/seed/" + encodeURIComponent(entry), + "image/jpeg", + "seed media " + entry, + ), + ), +); console.log("public release verified: admin, preview, assets, and seed media");