Git、GitHub Actions、Shell 与 Docker：从本地开发到 CI/CD 和容器化

修改代码 → 本地检查 → Git 提交 → PR 检查
                              ↓
合并 main → 再次验证 → 构建并推送镜像 → 记录 digest
                                      ↓
                         部署 → 健康检查 → 观察或回滚

 delivery-demo/
 ├─ package.json              # scripts and dependencies
 ├─ package-lock.json         # generated once, then committed
 ├─ tsconfig.json
 ├─ eslint.config.mjs
 ├─ src/readiness.ts
 ├─ src/server.ts
 ├─ tests/unit.test.mjs
 ├─ tests/integration.test.mjs
 ├─ db/migrate.mjs
 ├─ scripts/check.sh
 ├─ Dockerfile
 ├─ .dockerignore
 ├─ .env.example
 ├─ compose.yaml
 └─ .github/workflows/ci.yml

git status --short
git switch -c feature/readiness
git diff
git add -p
git diff --cached
git commit -m "feat: add database readiness check"
git push -u origin feature/readiness

Before:
A──B──C       main
   └──D       feature
 
Merge:
A──B──C──M    feature
   └──D──┘
 
Rebase:
A──B──C──D'   feature

git fetch origin
git rebase origin/main
# Resolve conflicts, then stage only resolved files.
git add src/server.ts
git rebase --continue
# Alternative while the rebase is still in progress:
# git rebase --abort

{
  "name": "delivery-demo",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "engines": { "node": ">=24 <25" },
  "scripts": {
    "lint": "eslint src",
    "typecheck": "tsc --noEmit",
    "build": "tsc",
    "test": "node --test tests/unit.test.mjs",
    "test:integration": "node --test tests/integration.test.mjs",
    "migrate": "node db/migrate.mjs",
    "start": "node dist/server.js"
  },
  "dependencies": { "pg": "^8.13.0" },
  "devDependencies": {
    "@eslint/js": "^9.0.0",
    "@types/node": "^24.0.0",
    "@types/pg": "^8.11.0",
    "eslint": "^9.0.0",
    "typescript": "^5.9.0",
    "typescript-eslint": "^8.0.0"
  }
}

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true,
    "noEmitOnError": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*.ts"]
}

import js from "@eslint/js";
import tseslint from "typescript-eslint";
 
export default tseslint.config(
  { ignores: ["dist/**", "node_modules/**"] },
  js.configs.recommended,
  ...tseslint.configs.recommended,
);

export async function readiness(probe: () => Promise<unknown>) {
  try {
    await probe();
    return { status: 200, body: { status: "ready" } };
  } catch {
    return { status: 503, body: { status: "unavailable" } };
  }
}

import { createServer } from "node:http";
import pg from "pg";
import { readiness } from "./readiness.js";
 
const pool = new pg.Pool({
  connectionTimeoutMillis: 2000,
  query_timeout: 2000,
});
pool.on("error", () => console.error("database pool error"));
 
const server = createServer(async (req, res) => {
  res.setHeader("Content-Type", "application/json");
  if (req.method !== "GET") {
    res.writeHead(405, { Allow: "GET" }).end();
    return;
  }
  if (req.url === "/healthz") {
    res.end(JSON.stringify({ status: "ok" }));
    return;
  }
  if (req.url === "/version") {
    res.end(JSON.stringify({ revision: process.env.APP_REVISION ?? "dev" }));
    return;
  }
  if (req.url === "/readyz") {
    const result = await readiness(() =>
      pool.query("SELECT id FROM service_checks LIMIT 0"),
    );
    res.statusCode = result.status;
    res.end(JSON.stringify(result.body));
    return;
  }
  res.writeHead(404).end(JSON.stringify({ error: "not_found" }));
});
 
const port = Number(process.env.PORT ?? 3000);
if (!Number.isInteger(port) || port < 1 || port > 65535) {
  throw new Error("Invalid PORT");
}
server.listen(port, process.env.HOST ?? "0.0.0.0");
 
let stopping = false;
function shutdown() {
  if (stopping) return;
  stopping = true;
  const deadline = setTimeout(() => process.exit(1), 10_000);
  deadline.unref();
  server.close(() => {
    void pool.end().then(() => {
      clearTimeout(deadline);
    }).catch(() => process.exit(1));
  });
}
process.on("SIGTERM", shutdown);
process.on("SIGINT", shutdown);

import pg from "pg";
 
const pool = new pg.Pool({ connectionTimeoutMillis: 2000 });
try {
  await pool.query(`
    CREATE TABLE IF NOT EXISTS service_checks (
      id UUID PRIMARY KEY,
      note TEXT NOT NULL
    )
  `);
} finally {
  await pool.end();
}

import test from "node:test";
import assert from "node:assert/strict";
import { readiness } from "../dist/readiness.js";
 
test("successful probe is ready", async () => {
  const result = await readiness(async () => undefined);
  assert.equal(result.status, 200);
  assert.deepEqual(result.body, { status: "ready" });
});
 
test("failed probe does not expose internal errors", async () => {
  const result = await readiness(async () => {
    throw new Error("private database details");
  });
  assert.equal(result.status, 503);
  assert.deepEqual(result.body, { status: "unavailable" });
});

import test from "node:test";
import assert from "node:assert/strict";
import { randomUUID } from "node:crypto";
import pg from "pg";
 
test("database round trip", async () => {
  const pool = new pg.Pool({ connectionTimeoutMillis: 2000 });
  let client;
  try {
    client = await pool.connect();
    await client.query("BEGIN");
    const id = randomUUID();
    await client.query(
      "INSERT INTO service_checks (id, note) VALUES ($1, $2)",
      [id, "integration-check"],
    );
    const result = await client.query(
      "SELECT note FROM service_checks WHERE id = $1", [id],
    );
    assert.equal(result.rows[0].note, "integration-check");
  } finally {
    try {
      if (client) await client.query("ROLLBACK");
    } finally {
      client?.release();
      await pool.end();
    }
  }
});

node dist/server.js > app.log 2> error.log
node dist/server.js >> app.log 2>&1

bash -c 'false | tee /dev/null; printf "status=%s\n" "$?"'
bash -o pipefail -c 'false | tee /dev/null; printf "status=%s\n" "$?"'

#!/usr/bin/env bash
set -euo pipefail
 
project_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
cd -- "$project_dir"
mkdir -p reports
 
trap 'code=$?; printf "check exit=%s\n" "$code" >&2' EXIT
 
npm run lint 2>&1 | tee reports/lint.log
npm run typecheck 2>&1 | tee reports/typecheck.log
npm run build 2>&1 | tee reports/build.log
npm test 2>&1 | tee reports/unit.log
 
if [[ "${RUN_INTEGRATION:-0}" == "1" ]]; then
  npm run test:integration 2>&1 | tee reports/integration.log
fi

#!/usr/bin/env bash
set -euo pipefail
git diff --cached --check

git config core.hooksPath .githooks
chmod +x .githooks/pre-commit

name: CI
 
on:
  pull_request:
  push:
    branches: [main]
  workflow_dispatch:
 
permissions:
  contents: read
 
concurrency:
  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
jobs:
  verify:
    runs-on: ubuntu-24.04
    timeout-minutes: 15
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_USER: demo
          POSTGRES_PASSWORD: ci-only-password
          POSTGRES_DB: delivery
        ports:
          - 5432:5432
        options: >-
          --health-cmd "pg_isready -U demo -d delivery"
          --health-interval 5s
          --health-timeout 3s
          --health-retries 10
    env:
      PGHOST: 127.0.0.1
      PGPORT: "5432"
      PGUSER: demo
      PGPASSWORD: ci-only-password
      PGDATABASE: delivery
      RUN_INTEGRATION: "1"
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: actions/setup-node@v7
        with:
          node-version: "24"
          cache: npm
          cache-dependency-path: package-lock.json
      - run: npm ci
      - run: npm run migrate
      - run: bash scripts/check.sh
      - name: Preserve check logs
        if: ${{ always() }}
        uses: actions/upload-artifact@v7
        with:
          name: check-logs-${{ github.run_id }}-${{ github.run_attempt }}
          path: reports/
          if-no-files-found: ignore
          retention-days: 7
 
  image:
    needs: verify
    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
    runs-on: ubuntu-24.04
    timeout-minutes: 20
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - name: Build, smoke-check and push
        shell: bash
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GH_ACTOR: ${{ github.actor }}
          REPOSITORY: ${{ github.repository }}
          REVISION: ${{ github.sha }}
        run: |
          set -euo pipefail
          image="ghcr.io/${REPOSITORY,,}:${REVISION}"
          docker build --build-arg "REVISION=$REVISION" -t "$image" .
          docker run --rm "$image" node --input-type=module -e \
            'await import("pg"); await import("./dist/readiness.js");'
          printf '%s' "$GH_TOKEN" | docker login ghcr.io -u "$GH_ACTOR" --password-stdin
          trap 'docker logout ghcr.io >/dev/null 2>&1 || true' EXIT
          docker push "$image"
          mkdir -p reports
          docker image inspect --format '{{index .RepoDigests 0}}' "$image" > reports/image.txt
          grep -Eq '^ghcr.io/.+@sha256:[0-9a-f]{64}$' reports/image.txt
          printf '%s\n' "$REVISION" > reports/commit.txt
      - uses: actions/upload-artifact@v7
        with:
          name: release-${{ github.sha }}-${{ github.run_attempt }}
          path: reports/
          retention-days: 30

# syntax=docker/dockerfile:1
FROM node:24-bookworm-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY tsconfig.json ./
COPY src ./src
COPY tests/unit.test.mjs ./tests/unit.test.mjs
RUN npm run build && npm test
 
FROM node:24-bookworm-slim AS production-deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev && npm cache clean --force
 
FROM node:24-bookworm-slim AS runtime
WORKDIR /app
ENV NODE_ENV=production
ARG REVISION=dev
ENV APP_REVISION=$REVISION
LABEL org.opencontainers.image.revision=$REVISION
COPY --from=production-deps --chown=node:node /app/node_modules ./node_modules
COPY --from=build --chown=node:node /app/dist ./dist
COPY --chown=node:node package.json ./
COPY --chown=node:node db ./db
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]

node_modules
dist
.git
.env
.env.*
reports
npm-debug.log*

POSTGRES_PASSWORD=local-demo-only
APP_REVISION=dev

x-app: &app
  image: delivery-demo:local
  build:
    context: .
    args:
      REVISION: ${APP_REVISION:-dev}
  environment:
    PGHOST: db
    PGPORT: "5432"
    PGUSER: demo
    PGPASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD}
    PGDATABASE: delivery
 
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: demo
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD}
      POSTGRES_DB: delivery
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U demo -d delivery"]
      interval: 5s
      timeout: 3s
      retries: 10
 
  migrate:
    <<: *app
    command: ["npm", "run", "migrate"]
    depends_on:
      db:
        condition: service_healthy
    restart: "no"
 
  api:
    <<: *app
    ports:
      - "127.0.0.1:3000:3000"
    depends_on:
      db:
        condition: service_healthy
      migrate:
        condition: service_completed_successfully
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/readyz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 5s
      timeout: 4s
      retries: 10
      start_period: 10s
    stop_grace_period: 15s
 
volumes:
  db-data:

npm install
cp .env.example .env
bash scripts/check.sh
docker compose config --quiet
docker compose up -d --build --wait --wait-timeout 120
curl --fail http://127.0.0.1:3000/readyz
curl --fail http://127.0.0.1:3000/version
docker compose ps
docker compose logs --tail=100 api migrate db

x-runtime: &runtime
  image: ${APP_IMAGE:?Set APP_IMAGE to a registry digest}
  environment:
    PGHOST: db
    PGPORT: "5432"
    PGUSER: demo
    PGPASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD}
    PGDATABASE: delivery
 
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: demo
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD}
      POSTGRES_DB: delivery
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U demo -d delivery"]
      interval: 5s
      timeout: 3s
      retries: 10
    restart: unless-stopped
 
  migrate:
    <<: *runtime
    command: ["npm", "run", "migrate"]
    depends_on:
      db:
        condition: service_healthy
    restart: "no"
 
  api:
    <<: *runtime
    ports:
      - "127.0.0.1:3000:3000"
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/readyz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 5s
      timeout: 4s
      retries: 10
      start_period: 10s
    restart: unless-stopped
    stop_grace_period: 15s
 
volumes:
  db-data:

#!/usr/bin/env bash
set -euo pipefail
: "${APP_IMAGE:?Set APP_IMAGE}"
: "${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD}"
if [[ ! "$APP_IMAGE" =~ ^ghcr\.io/.+@sha256:[0-9a-f]{64}$ ]]; then
  printf 'APP_IMAGE must be a GHCR digest reference\n' >&2
  exit 2
fi
export APP_IMAGE POSTGRES_PASSWORD
compose=(docker compose -p delivery -f compose.deploy.yaml)
"${compose[@]}" config --quiet
"${compose[@]}" pull
"${compose[@]}" up -d --wait --wait-timeout 120 db
"${compose[@]}" run --rm --no-deps migrate
"${compose[@]}" up -d --no-deps --wait --wait-timeout 120 api
curl --fail --silent --show-error --max-time 5 http://127.0.0.1:3000/readyz
curl --fail --silent --show-error --max-time 5 http://127.0.0.1:3000/version

: "${PREVIOUS_IMAGE:?Set the previously verified digest}"
APP_IMAGE="$PREVIOUS_IMAGE" docker compose -p delivery -f compose.deploy.yaml \
  up -d --no-deps --pull always --wait --wait-timeout 120 api