chore: 固化一键生产部署流程
CI / Static checks (push) Has been cancelled
CI / Production build (push) Has been cancelled
CI / API integration (push) Has been cancelled
CI / Browser regression (push) Has been cancelled

This commit is contained in:
que01 committed 2026-10-13 14:56:16 +08:00
1 parent c78deafee3
commit 47a24e0d53
6 files changed
+189 -40

No files matched your search

-11
View File
@@ -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,
},
],
};
+61 -6
View File
@@ -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"),
+15 -3
View File
@@ -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` 创建管理员与演示品牌。已有生产环境禁止重复执行种子命令;模板示例内容只能由管理员在后台对指定品牌显式导入,不能把示例数据扩展到全局种子。
+1
View File
@@ -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",
+83
View File
@@ -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);
+29 -20
View File
@@ -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");