@kernel-sig/console 0.1.0

package/cli/index.js

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+/**
+ * ksc —— 一条命令在本机起一整套 Kernel SIG 平台。
+ *
+ * 它自己不实现任何业务，只做四件事：确认 Docker 可用、备好配置文件、
+ * 把 docker compose 拉起来、等健康检查通过后把地址报出来。
+ *
+ * 两点值得说明：
+ *
+ * 1. **配置目录刻意放在包目录之外**。`npx` 把包解到 `~/.npm/_npx/<hash>/`，
+ *    升级一次版本就换一个目录 —— 配置和密钥放那里等于每次升级都丢一次，
+ *    而 KSC_SECRET_KEY 一变，库里加密存的 token 就再也解不开了。
+ *
+ * 2. **`compose.yaml` 用 `-f` 指定，而不是 cd 过去**。compose 里
+ *    `build.context: ./backend` 是相对 compose 文件所在目录解析的，
+ *    所以必须在包目录这一侧构建；数据则落在具名卷上，与 cwd 无关，
+ *    换目录、换版本都不会丢。
+ */
+
+'use strict'
+
+const { spawn, spawnSync } = require('node:child_process')
+const crypto = require('node:crypto')
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+const PKG_DIR = path.resolve(__dirname, '..')
+const COMPOSE_FILE = path.join(PKG_DIR, 'compose.yaml')
+const ENV_TEMPLATE = path.join(PKG_DIR, '.env.example')
+
+const DEFAULT_DIR = path.join(os.homedir(), '.kernel-sig')
+const DEFAULT_PORT = '18080'
+
+// .env.example 里那句占位。它本身长度就超过 32，所以不能只看长度，
+// 得显式比对 —— 否则使用者会拿一句人人皆知的字符串当加密密钥用。
+const SECRET_PLACEHOLDER = 'please-change-me-to-a-random-32-plus-char-string'
+
+const HELP = `
+ksc —— 在本机运行 Kernel SIG 平台
+
+用法：
+  ksc [命令] [选项]
+
+命令：
+  up        构建并启动（默认）
+  down      停止容器；数据保留在 docker 卷里
+  logs      跟踪日志
+  status    查看容器状态
+
+选项：
+  --token <token>   AtomGit 访问令牌。给了就自动导入并开始同步；
+                    不给也能起，只是没有数据（界面上会提示去补）
+  --dir <目录>      配置目录，默认 ~/.kernel-sig
+  --open            就绪后打开浏览器
+  -h, --help        显示这段说明
+
+例子：
+  npx @kernel-sig/console --token ghp_xxx --open
+  ksc logs
+`
+
+function log(message) {
+  process.stdout.write(`${message}\n`)
+}
+
+function fail(message) {
+  process.stderr.write(`\n错误：${message}\n`)
+  process.exit(1)
+}
+
+// ---------------------------------------------------------------------------
+// 参数
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const opts = { command: 'up', dir: DEFAULT_DIR, token: null, open: false, help: false }
+  const commands = new Set(['up', 'down', 'logs', 'status'])
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '-h' || arg === '--help') {
+      opts.help = true
+    } else if (arg === '--open') {
+      opts.open = true
+    } else if (arg === '--token') {
+      opts.token = argv[i + 1]
+      if (!opts.token) fail('--token 后面要跟一个令牌值')
+      i += 1
+    } else if (arg === '--dir') {
+      const value = argv[i + 1]
+      if (!value) fail('--dir 后面要跟一个目录路径')
+      opts.dir = path.resolve(value)
+      i += 1
+    } else if (!arg.startsWith('-') && commands.has(arg)) {
+      opts.command = arg
+    } else {
+      fail(`无法识别的参数「${arg}」，用 --help 看用法`)
+    }
+  }
+  return opts
+}
+
+// ---------------------------------------------------------------------------
+// Docker
+// ---------------------------------------------------------------------------
+
+function dockerMissing() {
+  const probe = spawnSync('docker', ['compose', 'version'], { stdio: 'ignore' })
+  return probe.error !== undefined || probe.status !== 0
+}
+
+function daemonDown() {
+  const probe = spawnSync('docker', ['info'], { stdio: 'ignore' })
+  return probe.error !== undefined || probe.status !== 0
+}
+
+function requireDocker() {
+  if (dockerMissing()) {
+    fail(
+      '没找到 docker compose。\n\n' +
+        '  这个平台跑在容器里，需要先装 Docker：\n' +
+        '    macOS / Windows  https://docs.docker.com/desktop/\n' +
+        '    Linux            https://docs.docker.com/engine/install/\n\n' +
+        '  装完用 `docker compose version` 确认一下。'
+    )
+  }
+  if (daemonDown()) {
+    fail('Docker 装了，但服务没在跑。启动 Docker Desktop（或 `systemctl start docker`）后重试。')
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 配置文件
+// ---------------------------------------------------------------------------
+
+function readEnvValue(content, key) {
+  const matched = content.match(new RegExp(`^${key}=(.*)$`, 'm'))
+  return matched ? matched[1].trim() : null
+}
+
+function writeEnvValue(content, key, value) {
+  const pattern = new RegExp(`^${key}=.*$`, 'm')
+  if (pattern.test(content)) return content.replace(pattern, `${key}=${value}`)
+  return `${content.replace(/\s*$/, '')}\n${key}=${value}\n`
+}
+
+/**
+ * 备好配置目录与 .env，返回 .env 的路径。
+ *
+ * 密钥只在缺的时候生成：已经有一套数据的人不该因为重跑一次命令就换密钥，
+ * 那会让库里所有加密凭据作废。
+ */
+function prepareConfig(opts) {
+  // mode 只在目录**首次创建**时生效，已存在的目录不受影响 —— 所以还要
+  // 显式 chmod 一次，否则预建过目录的人拿到的是 umask 给的 0755。
+  fs.mkdirSync(opts.dir, { recursive: true, mode: 0o700 })
+  fs.chmodSync(opts.dir, 0o700)
+
+  const envFile = path.join(opts.dir, '.env')
+  const isNew = !fs.existsSync(envFile)
+  let content = isNew
+    ? fs.readFileSync(ENV_TEMPLATE, 'utf8')
+    : fs.readFileSync(envFile, 'utf8')
+
+  const secret = readEnvValue(content, 'KSC_SECRET_KEY')
+  if (!secret || secret === SECRET_PLACEHOLDER || secret.length < 32) {
+    content = writeEnvValue(content, 'KSC_SECRET_KEY', crypto.randomBytes(32).toString('hex'))
+    log(`  · 已生成 KSC_SECRET_KEY（64 位十六进制，写在 ${envFile}）`)
+  }
+
+  const token = opts.token || process.env.KSC_ATOMGIT_TOKEN
+  if (opts.token) {
+    content = writeEnvValue(content, 'KSC_ATOMGIT_TOKEN', opts.token)
+  }
+
+  // 目录 0700、文件 0600：.env 里是密钥，同机器上的其他用户不该读得到
+  fs.writeFileSync(envFile, content, { mode: 0o600 })
+  fs.chmodSync(envFile, 0o600)
+
+  return { envFile, content, hasToken: Boolean(readEnvValue(content, 'KSC_ATOMGIT_TOKEN')) }
+}
+
+function webPort(content) {
+  return readEnvValue(content, 'KSC_WEB_PORT') || DEFAULT_PORT
+}
+
+// ---------------------------------------------------------------------------
+// compose
+// ---------------------------------------------------------------------------
+
+/**
+ * 跑一条 compose 子命令。
+ *
+ * **显式给一个自己的项目名**，盖过 `compose.yaml` 顶部的 `name:`。这样
+ * `ksc` 起的容器和数据卷与仓库里的 `make up` 完全是两套。
+ *
+ * 不加这个的话，两者抢同一套容器，而且是**静默**出错：两边用各自的
+ * `.env`，`KSC_SECRET_KEY` 不一样，compose 于是把容器重建一遍 —— 服务照常
+ * 起来、健康检查照常通过，但库里加密存的 token 从此解不开，谁也看不出
+ * 为什么。加到不同项目名之后，同机同时跑只会撞端口，那是响亮且无害的失败。
+ */
+const PROJECT = 'kernel-sig'
+
+function compose(envFile, args) {
+  return spawnSync(
+    'docker',
+    ['compose', '--project-name', PROJECT, '--env-file', envFile, '-f', COMPOSE_FILE, ...args],
+    { stdio: 'inherit' }
+  )
+}
+
+function openBrowser(url) {
+  const command =
+    process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open'
+  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url]
+  try {
+    spawn(command, args, { detached: true, stdio: 'ignore' }).unref()
+  } catch {
+    // 打不开浏览器不是错误，地址已经打印出来了
+  }
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+/**
+ * 等后端健康检查通过。
+ *
+ * 走的是前端 nginx 的同源路径（`/api/v1/healthz` 由 nginx 转给后端），
+ * 所以这一条通过就意味着"浏览器打开能拿到东西"，而不只是后端活着。
+ */
+async function waitHealthy(port, timeoutMs) {
+  const url = `http://127.0.0.1:${port}/api/v1/healthz`
+  const deadline = Date.now() + timeoutMs
+  let waited = 0
+
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(url, { signal: AbortSignal.timeout(3000) })
+      if (response.ok) return true
+    } catch {
+      // 还没起来，继续等
+    }
+    await sleep(2000)
+    waited += 2
+    if (waited % 20 === 0) log(`  · 还在启动…（已等 ${waited} 秒）`)
+  }
+  return false
+}
+
+// ---------------------------------------------------------------------------
+// 命令
+// ---------------------------------------------------------------------------
+
+async function commandUp(opts) {
+  requireDocker()
+
+  log(`配置目录 ${opts.dir}`)
+  const { envFile, content, hasToken } = prepareConfig(opts)
+  const port = webPort(content)
+
+  log('构建并启动容器（首次要几分钟，之后镜像有缓存会快很多）…')
+  const result = compose(envFile, ['up', '-d', '--build'])
+  if (result.status !== 0) {
+    fail(`docker compose 启动失败（退出码 ${result.status}）。用 \`ksc logs\` 看日志。`)
+  }
+
+  log('等待服务就绪…')
+  const healthy = await waitHealthy(port, 10 * 60 * 1000)
+  const url = `http://localhost:${port}/`
+
+  if (!healthy) {
+    fail(
+      `等了 10 分钟服务还没就绪。\n\n` +
+        `  看日志： ksc logs\n` +
+        `  看状态： ksc status\n\n` +
+        `  最常见的原因是端口被占用（默认 ${DEFAULT_PORT}，本机可能已有别的服务）。\n` +
+        `  换个端口：改 ${envFile} 里的 KSC_WEB_PORT 等几项，然后重跑。`
+    )
+  }
+
+  log('')
+  log(`  就绪：${url}`)
+  if (!hasToken) {
+    log('')
+    log('  没有 AtomGit token，openeuler/kernel 已纳管但不会拉数据。')
+    log('  补上它： ksc --token <token>')
+    log('  或者在界面「设置 → 凭据」里添加。')
+  }
+  log('')
+
+  if (opts.open) openBrowser(url)
+  return 0
+}
+
+function commandDown(opts) {
+  requireDocker()
+  const { envFile } = prepareConfig(opts)
+  const result = compose(envFile, ['down'])
+  if (result.status !== 0) fail(`停止失败（退出码 ${result.status}）`)
+  log('')
+  log('  已停止。数据还在 docker 卷里，下次启动就在。')
+  log(`  要连数据一起清掉： docker volume rm ${PROJECT}_postgres-data ${PROJECT}_valkey-data`)
+  log('')
+  return 0
+}
+
+function commandLogs(opts) {
+  requireDocker()
+  const { envFile } = prepareConfig(opts)
+  const result = compose(envFile, ['logs', '-f', '--tail=100'])
+  return result.status === 0 ? 0 : 1
+}
+
+function commandStatus(opts) {
+  requireDocker()
+  const { envFile } = prepareConfig(opts)
+  const result = compose(envFile, ['ps'])
+  return result.status === 0 ? 0 : 1
+}
+
+// ---------------------------------------------------------------------------
+
+async function main(argv) {
+  const opts = parseArgs(argv)
+  if (opts.help) {
+    log(HELP)
+    return 0
+  }
+  if (opts.command === 'down') return commandDown(opts)
+  if (opts.command === 'logs') return commandLogs(opts)
+  if (opts.command === 'status') return commandStatus(opts)
+  return commandUp(opts)
+}
+
+main(process.argv.slice(2))
+  .then((code) => process.exit(code))
+  .catch((error) => fail(error && error.message ? error.message : String(error)))

package/compose.yaml

@@ -0,0 +1,105 @@
+name: kernel-sig-console
+
+x-backend-env: &backend-env
+  KSC_SECRET_KEY: ${KSC_SECRET_KEY:?必须设置 KSC_SECRET_KEY，可用 openssl rand -hex 32 生成}
+  KSC_ENVIRONMENT: ${KSC_ENVIRONMENT:-production}
+  KSC_LOG_LEVEL: ${KSC_LOG_LEVEL:-INFO}
+  KSC_COOKIE_SECURE: ${KSC_COOKIE_SECURE:-false}
+  KSC_DATABASE_URL: postgresql+asyncpg://${KSC_DB_USER:-kernel_sig}:${KSC_DB_PASSWORD:-kernel_sig}@postgres:5432/${KSC_DB_NAME:-kernel_sig}
+  KSC_VALKEY_URL: redis://valkey:6379/0
+  KSC_BOOTSTRAP_ADMIN_USERNAME: ${KSC_BOOTSTRAP_ADMIN_USERNAME:-admin}
+  KSC_BOOTSTRAP_ADMIN_PASSWORD: ${KSC_BOOTSTRAP_ADMIN_PASSWORD:-}
+  KSC_BOOTSTRAP_ADMIN_EMAIL: ${KSC_BOOTSTRAP_ADMIN_EMAIL:-admin@localhost}
+  # 这里是显式白名单：不在其中的变量进不了容器，哪怕 .env 里写了。
+  KSC_BOOTSTRAP_REPOSITORY: ${KSC_BOOTSTRAP_REPOSITORY:-openeuler/kernel}
+  KSC_ATOMGIT_TOKEN: ${KSC_ATOMGIT_TOKEN:-}
+
+services:
+  postgres:
+    image: ${DOCKER_REGISTRY:-docker.io}/library/postgres:17-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: ${KSC_DB_NAME:-kernel_sig}
+      POSTGRES_USER: ${KSC_DB_USER:-kernel_sig}
+      POSTGRES_PASSWORD: ${KSC_DB_PASSWORD:-kernel_sig}
+      POSTGRES_INITDB_ARGS: "--encoding=UTF8"
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    ports:
+      - "127.0.0.1:${KSC_POSTGRES_PORT:-15432}:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${KSC_DB_USER:-kernel_sig} -d ${KSC_DB_NAME:-kernel_sig}"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
+  valkey:
+    image: ${DOCKER_REGISTRY:-docker.io}/valkey/valkey:8-alpine
+    restart: unless-stopped
+    command: ["valkey-server", "--save", "60", "1", "--appendonly", "yes"]
+    volumes:
+      - valkey-data:/data
+    ports:
+      - "127.0.0.1:${KSC_VALKEY_PORT:-16379}:6379"
+    healthcheck:
+      test: ["CMD", "valkey-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
+  backend:
+    build:
+      context: ./backend
+      args:
+        DOCKER_REGISTRY: ${DOCKER_REGISTRY:-docker.io}
+        PIP_INDEX_URL: ${PIP_INDEX_URL:-https://pypi.tuna.tsinghua.edu.cn/simple}
+    restart: unless-stopped
+    environment: *backend-env
+    depends_on:
+      postgres:
+        condition: service_healthy
+      valkey:
+        condition: service_healthy
+    ports:
+      - "127.0.0.1:${KSC_API_PORT:-18000}:8000"
+
+  worker:
+    build:
+      context: ./backend
+      args:
+        DOCKER_REGISTRY: ${DOCKER_REGISTRY:-docker.io}
+        PIP_INDEX_URL: ${PIP_INDEX_URL:-https://pypi.tuna.tsinghua.edu.cn/simple}
+    # 复用 backend 镜像，只换启动命令。迁移由 backend 负责执行，
+    # worker 等它就绪再接活，避免两个进程同时跑 alembic。
+    command: ["arq", "app.worker.WorkerSettings"]
+    restart: unless-stopped
+    environment: *backend-env
+    depends_on:
+      backend:
+        condition: service_healthy
+      valkey:
+        condition: service_healthy
+    # 继承自 Dockerfile 的健康检查打的是 API 端口，对 worker 无意义
+    healthcheck:
+      test: ["CMD", "arq", "--check", "app.worker.WorkerSettings"]
+      interval: 30s
+      timeout: 10s
+      start_period: 30s
+      retries: 3
+
+  frontend:
+    build:
+      context: ./frontend
+      args:
+        DOCKER_REGISTRY: ${DOCKER_REGISTRY:-docker.io}
+        NPM_REGISTRY: ${NPM_REGISTRY:-https://registry.npmjs.org}
+    restart: unless-stopped
+    depends_on:
+      backend:
+        condition: service_healthy
+    ports:
+      - "${KSC_WEB_PORT:-18080}:80"
+
+volumes:
+  postgres-data:
+  valkey-data:

package/frontend/.dockerignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+.vite/
+*.tsbuildinfo

package/frontend/Dockerfile

@@ -0,0 +1,27 @@
+ARG DOCKER_REGISTRY=docker.io
+
+FROM ${DOCKER_REGISTRY}/library/node:22-alpine AS build
+WORKDIR /app
+
+ARG NPM_REGISTRY=https://registry.npmjs.org
+RUN npm config set registry "${NPM_REGISTRY}"
+
+# 先装依赖再拷源码，让依赖层在源码变更时仍可复用
+COPY package.json package-lock.json* ./
+RUN npm install --no-audit --no-fund
+
+COPY . .
+RUN npm run build
+
+FROM ${DOCKER_REGISTRY}/library/nginx:1.27-alpine AS runtime
+
+COPY --from=build /app/dist /usr/share/nginx/html
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+
+EXPOSE 80
+
+# 必须写 127.0.0.1 而不是 localhost：busybox 的 wget 会优先解析到 ::1，
+# 而 nginx 只监听 IPv4 的 0.0.0.0:80，探测一律 "connection refused"，
+# 容器会永远停在 health: starting。
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD wget -q --spider http://127.0.0.1/ || exit 1

package/frontend/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="color-scheme" content="dark light" />
+    <meta name="description" content="openEuler Kernel SIG 协作平台" />
+    <title>Kernel SIG Console</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/frontend/nginx.conf

@@ -0,0 +1,47 @@
+server {
+    listen 80;
+    server_name _;
+
+    root /usr/share/nginx/html;
+    index index.html;
+
+    gzip on;
+    gzip_types text/css application/javascript application/json image/svg+xml;
+    gzip_min_length 1024;
+    gzip_vary on;
+
+    # 安全响应头。注意 CSP 未启用：SPA 的 Vite 产物需要内联样式，
+    # 贸然开启会破坏样式且此处收益有限。
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header X-Frame-Options "DENY" always;
+    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+
+    # 带内容哈希的静态资源可长缓存
+    location /assets/ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+        try_files $uri =404;
+    }
+
+    location /api/ {
+        proxy_pass http://backend:8000;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_read_timeout 300s;
+        proxy_send_timeout 300s;
+
+        # AI 分析结果通过 SSE 推送，必须关闭缓冲，
+        # 否则 Nginx 会攒够缓冲才发给浏览器，前端表现为"卡住不更新"
+        proxy_buffering off;
+        proxy_cache off;
+        proxy_set_header Connection "";
+    }
+
+    # SPA 路由回退：未命中的路径交给前端路由处理
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+}