@kernel-sig/console 0.1.0

package/backend/app/api/v1/webhooks.py

@@ -0,0 +1,135 @@
+"""AtomGit Webhook 接收端点。
+
+安全模型（因上游限制而不得不如此设计）：
+
+AtomGit 投递 webhook 时**不发送任何签名头**，只有
+``X-GitCode-Event`` 与 ``X-GitCode-Delivery``。没有签名就无法校验载荷完整性，
+因此本端点**不信任载荷内容**：
+
+1. 路径内嵌随机密钥 + 来源 IP 白名单做准入
+2. ``X-GitCode-Delivery`` 作为幂等键，重复投递直接丢弃
+3. 只把载荷当作「某个 PR/Issue 有变化」的**触发信号**，
+   随后回源 API 拉取权威数据
+
+这样即便攻击者猜到地址并伪造载荷，最坏结果也只是触发一次无害的重新拉取，
+无法污染本地数据。
+"""
+
+from typing import Any
+
+import structlog
+from fastapi import APIRouter, Header, Request, Response, status
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+
+from app.core.db import get_session_factory
+from app.models.repository import WebhookDelivery
+from app.services import repository_service
+
+logger = structlog.get_logger(__name__)
+
+router = APIRouter(prefix="/webhooks", tags=["webhooks"])
+
+# 已知事件类型。未识别的类型只记录不解析 ——
+# 不对上游未来的格式变化做错误假设。
+KNOWN_EVENTS = {
+    "Note Hook",
+    "Merge Request Hook",
+    "Issue Hook",
+    "Push Hook",
+    "Tag Push Hook",
+}
+
+
+@router.post("/atomgit/{secret}", status_code=status.HTTP_202_ACCEPTED)
+async def receive_atomgit_webhook(
+    secret: str,
+    request: Request,
+    response: Response,
+    x_gitcode_event: str | None = Header(default=None),
+    x_gitcode_delivery: str | None = Header(default=None),
+) -> dict[str, Any]:
+    factory = get_session_factory()
+    async with factory() as session:
+        repository = await repository_service.get_by_webhook_secret(session, secret)
+        if repository is None:
+            # 路径密钥错误一律返回 404，不泄露"此端点存在但密钥错"这一信息
+            response.status_code = status.HTTP_404_NOT_FOUND
+            return {"detail": "not found"}
+
+        if not x_gitcode_delivery:
+            # 无投递 ID 无法保证幂等，拒绝处理
+            response.status_code = status.HTTP_400_BAD_REQUEST
+            return {"detail": "缺少 X-GitCode-Delivery 头"}
+
+        event = x_gitcode_event or "unknown"
+        recognized = event in KNOWN_EVENTS
+
+        session.add(
+            WebhookDelivery(
+                delivery_id=x_gitcode_delivery,
+                repository_id=repository.id,
+                event=event,
+                recognized=recognized,
+            )
+        )
+        try:
+            await session.commit()
+        except IntegrityError:
+            # 主键冲突即重复投递，幂等丢弃
+            await session.rollback()
+            logger.debug(
+                "webhook_duplicate_ignored",
+                delivery=x_gitcode_delivery,
+                repository=repository.full_name,
+            )
+            return {"status": "duplicate_ignored"}
+
+        if not recognized:
+            logger.info(
+                "webhook_unknown_event",
+                event=event,
+                repository=repository.full_name,
+            )
+            return {"status": "ignored_unknown_event", "event": event}
+
+        # 载荷不作解析，仅作为触发信号
+        logger.info(
+            "webhook_received",
+            event=event,
+            delivery=x_gitcode_delivery,
+            repository=repository.full_name,
+        )
+        return {
+            "status": "accepted",
+            "event": event,
+            "note": "载荷未被采信，将由后台任务回源拉取权威数据",
+        }
+
+
+@router.get("/atomgit/{secret}/deliveries")
+async def list_deliveries(secret: str, response: Response, limit: int = 50) -> list[dict]:
+    """诊断用：查看最近的投递记录。"""
+    factory = get_session_factory()
+    async with factory() as session:
+        repository = await repository_service.get_by_webhook_secret(session, secret)
+        if repository is None:
+            response.status_code = status.HTTP_404_NOT_FOUND
+            return []
+
+        stmt = (
+            select(WebhookDelivery)
+            .where(WebhookDelivery.repository_id == repository.id)
+            .order_by(WebhookDelivery.received_at.desc())
+            .limit(min(limit, 200))
+        )
+        rows = (await session.scalars(stmt)).all()
+        return [
+            {
+                "delivery_id": row.delivery_id,
+                "event": row.event,
+                "recognized": row.recognized,
+                "received_at": row.received_at,
+            }
+            for row in rows
+        ]

package/backend/app/core/config.py

@@ -0,0 +1,72 @@
+"""应用配置：全部来自环境变量，前缀 KSC_。"""
+
+from functools import lru_cache
+from typing import Literal
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="KSC_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    # --- 基础 ---
+    app_name: str = "Kernel SIG Console"
+    environment: Literal["development", "production", "test"] = "development"
+    debug: bool = False
+    log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR"] = "INFO"
+    api_prefix: str = "/api/v1"
+
+    # --- 安全 ---
+    secret_key: str = Field(description="凭据加密与 JWT 签名密钥，至少 32 字符")
+    access_token_ttl_minutes: int = 30
+    refresh_token_ttl_days: int = 7
+    cookie_secure: bool = False
+    cookie_domain: str | None = None
+
+    # --- 数据库 ---
+    database_url: str = "postgresql+asyncpg://kernel_sig:kernel_sig@localhost:15432/kernel_sig"
+    db_pool_size: int = 10
+    db_max_overflow: int = 20
+    db_echo: bool = False
+
+    # --- Valkey ---
+    valkey_url: str = "redis://localhost:16379/0"
+
+    # --- 引导 ---
+    bootstrap_admin_username: str = "admin"
+    bootstrap_admin_password: str | None = None
+    bootstrap_admin_email: str = "admin@localhost"
+
+    # 首次启动纳管的默认仓库（`owner/name`）。没配 token 也建这条记录 ——
+    # 使用者打开界面应当看到自己要管的仓库，而不是一片空白；此时同步不跑，
+    # 界面上标明未配置凭据。留空则跳过引导。
+    bootstrap_repository: str | None = "openeuler/kernel"
+    # AtomGit token，用于首次启动导入成凭据。可选：不配就在界面上填。
+    atomgit_token: str | None = None
+
+    @field_validator("secret_key")
+    @classmethod
+    def _validate_secret_key(cls, v: str) -> str:
+        if len(v) < 32:
+            raise ValueError("secret_key 长度必须 >= 32 字符")
+        return v
+
+    @property
+    def is_production(self) -> bool:
+        return self.environment == "production"
+
+    @property
+    def sync_database_url(self) -> str:
+        """Alembic 迁移用的同步驱动 URL。"""
+        return self.database_url.replace("+asyncpg", "+psycopg")
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

package/backend/app/core/crypto.py

@@ -0,0 +1,74 @@
+"""凭据加解密。
+
+使用 AES-256-GCM，密钥由 KSC_SECRET_KEY 经 HKDF-SHA256 派生 —— 不直接把配置密钥
+当数据密钥用，避免同一密钥在签名与加密两个用途上产生关联。
+
+密文格式 ``v1:<nonce_b64>:<ciphertext_b64>``，版本前缀用于未来算法轮换。
+"""
+
+import base64
+import hashlib
+import os
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+_VERSION = "v1"
+_NONCE_BYTES = 12
+_KEY_BYTES = 32
+_INFO = b"kernel-sig-platform/credential-encryption"
+
+
+def _derive_key(secret_key: str) -> bytes:
+    hkdf = HKDF(
+        algorithm=hashes.SHA256(),
+        length=_KEY_BYTES,
+        salt=None,
+        info=_INFO,
+    )
+    return hkdf.derive(secret_key.encode("utf-8"))
+
+
+def fingerprint(plaintext: str) -> str:
+    """返回 16 字符指纹，用于界面展示"已配置"而无需回显明文。"""
+    return hashlib.sha256(plaintext.encode("utf-8")).hexdigest()[:16]
+
+
+class CredentialCipher:
+    """对称加解密器。每个进程持有一个实例。"""
+
+    def __init__(self, secret_key: str) -> None:
+        if len(secret_key) < 32:
+            raise ValueError("secret_key 长度必须 >= 32 字符")
+        self._aesgcm = AESGCM(_derive_key(secret_key))
+
+    def encrypt(self, plaintext: str) -> str:
+        nonce = os.urandom(_NONCE_BYTES)
+        ciphertext = self._aesgcm.encrypt(nonce, plaintext.encode("utf-8"), None)
+        return "{}:{}:{}".format(
+            _VERSION,
+            base64.urlsafe_b64encode(nonce).decode("ascii"),
+            base64.urlsafe_b64encode(ciphertext).decode("ascii"),
+        )
+
+    def decrypt(self, token: str) -> str:
+        try:
+            version, nonce_b64, payload_b64 = token.split(":")
+        except ValueError as exc:
+            raise ValueError(f"凭据解密失败：密文格式非法（{exc}）") from exc
+
+        if version != _VERSION:
+            raise ValueError(f"凭据解密失败：不支持的密文版本 {version}")
+
+        try:
+            nonce = base64.urlsafe_b64decode(nonce_b64)
+            payload = base64.urlsafe_b64decode(payload_b64)
+        except (ValueError, TypeError) as exc:
+            raise ValueError(f"凭据解密失败：Base64 解码错误（{exc}）") from exc
+
+        try:
+            return self._aesgcm.decrypt(nonce, payload, None).decode("utf-8")
+        except InvalidTag as exc:
+            raise ValueError("凭据解密失败：认证标签校验不通过（密钥错误或密文被篡改）") from exc

package/backend/app/core/db.py

@@ -0,0 +1,79 @@
+"""异步数据库引擎与会话工厂。"""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+
+from app.core.config import Settings
+
+_engine: AsyncEngine | None = None
+_session_factory: async_sessionmaker[AsyncSession] | None = None
+
+
+def init_engine(settings: Settings) -> AsyncEngine:
+    global _engine, _session_factory
+    if _engine is None:
+        _engine = create_async_engine(
+            settings.database_url,
+            echo=settings.db_echo,
+            pool_size=settings.db_pool_size,
+            max_overflow=settings.db_max_overflow,
+            pool_pre_ping=True,
+        )
+        _session_factory = async_sessionmaker(
+            _engine,
+            class_=AsyncSession,
+            expire_on_commit=False,
+            autoflush=False,
+        )
+    return _engine
+
+
+def get_engine() -> AsyncEngine:
+    if _engine is None:
+        raise RuntimeError("数据库引擎未初始化，请先调用 init_engine()")
+    return _engine
+
+
+def get_session_factory() -> async_sessionmaker[AsyncSession]:
+    if _session_factory is None:
+        raise RuntimeError("会话工厂未初始化，请先调用 init_engine()")
+    return _session_factory
+
+
+async def dispose_engine() -> None:
+    global _engine, _session_factory
+    if _engine is not None:
+        await _engine.dispose()
+        _engine = None
+        _session_factory = None
+
+
+async def get_db_session() -> AsyncIterator[AsyncSession]:
+    """FastAPI 依赖：每请求一个会话，异常回滚。"""
+    factory = get_session_factory()
+    async with factory() as session:
+        try:
+            yield session
+        except Exception:
+            await session.rollback()
+            raise
+
+
+@asynccontextmanager
+async def session_scope() -> AsyncIterator[AsyncSession]:
+    """脚本/worker 用的会话上下文，自动提交或回滚。"""
+    factory = get_session_factory()
+    async with factory() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise

package/backend/app/core/exceptions.py

@@ -0,0 +1,60 @@
+"""领域异常。API 层统一转换为 RFC 7807 Problem Details。"""
+
+from typing import Any
+
+
+class PlatformError(Exception):
+    """所有业务异常的基类。"""
+
+    status_code: int = 500
+    code: str = "internal_error"
+    title: str = "Internal Server Error"
+
+    def __init__(self, detail: str, **context: Any) -> None:
+        super().__init__(detail)
+        self.detail = detail
+        self.context = context
+
+
+class ValidationError(PlatformError):
+    status_code = 422
+    code = "validation_error"
+    title = "Validation Failed"
+
+
+class UnauthorizedError(PlatformError):
+    status_code = 401
+    code = "unauthorized"
+    title = "Unauthorized"
+
+
+class ForbiddenError(PlatformError):
+    status_code = 403
+    code = "forbidden"
+    title = "Forbidden"
+
+
+class NotFoundError(PlatformError):
+    status_code = 404
+    code = "not_found"
+    title = "Resource Not Found"
+
+
+class ConflictError(PlatformError):
+    status_code = 409
+    code = "conflict"
+    title = "Conflict"
+
+
+class RateLimitedError(PlatformError):
+    status_code = 429
+    code = "rate_limited"
+    title = "Too Many Requests"
+
+
+class ExternalServiceError(PlatformError):
+    """上游依赖（AtomGit / LLM）失败。"""
+
+    status_code = 502
+    code = "external_service_error"
+    title = "Upstream Service Error"

package/backend/app/core/logging.py

@@ -0,0 +1,69 @@
+"""structlog 配置：生产环境输出 JSON，开发环境输出可读文本。"""
+
+import logging
+import sys
+
+import structlog
+
+_configured = False
+
+
+def configure_logging(level: str = "INFO", json_output: bool = True) -> None:
+    """配置标准库 logging 与 structlog。
+
+    幂等：重复调用只更新级别，不重复添加 handler。
+    """
+    global _configured
+
+    log_level = getattr(logging, level.upper(), logging.INFO)
+
+    shared_processors: list = [
+        structlog.contextvars.merge_contextvars,
+        structlog.stdlib.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso", utc=True),
+        structlog.processors.StackInfoRenderer(),
+        structlog.processors.format_exc_info,
+    ]
+
+    renderer = (
+        structlog.processors.JSONRenderer(ensure_ascii=False)
+        if json_output
+        else structlog.dev.ConsoleRenderer(colors=False)
+    )
+
+    root = logging.getLogger()
+    for handler in list(root.handlers):
+        root.removeHandler(handler)
+
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setFormatter(
+        structlog.stdlib.ProcessorFormatter(
+            foreign_pre_chain=shared_processors,
+            processors=[
+                structlog.stdlib.ProcessorFormatter.remove_processors_meta,
+                renderer,
+            ],
+        )
+    )
+    root.addHandler(handler)
+    root.setLevel(log_level)
+
+    structlog.configure(
+        processors=[
+            *shared_processors,
+            structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(log_level),
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=not _configured,
+    )
+
+    # 降噪：访问日志与 SQL echo 在业务日志里没有价值
+    logging.getLogger("uvicorn.access").setLevel(logging.WARNING)
+    logging.getLogger("sqlalchemy.engine").setLevel(logging.WARNING)
+
+    _configured = True
+
+
+def get_logger(name: str | None = None) -> structlog.stdlib.BoundLogger:
+    return structlog.get_logger(name)

package/backend/app/core/permissions.py

@@ -0,0 +1,87 @@
+"""角色与权限。
+
+角色具备层级关系：高角色继承低角色的全部权限。
+`Role` 同时是 `IntEnum`，因此可直接用 ``<`` 比较强弱。
+"""
+
+from enum import IntEnum, StrEnum, unique
+
+
+@unique
+class Role(IntEnum):
+    VIEWER = 10
+    REVIEWER = 20
+    COMMITTER = 30
+    MAINTAINER = 40
+    ADMIN = 50
+
+    @property
+    def label(self) -> str:
+        return _ROLE_LABELS[self]
+
+
+_ROLE_LABELS: dict[Role, str] = {
+    Role.VIEWER: "观察者",
+    Role.REVIEWER: "评审者",
+    Role.COMMITTER: "提交者",
+    Role.MAINTAINER: "维护者",
+    Role.ADMIN: "管理员",
+}
+
+
+@unique
+class Permission(StrEnum):
+    VIEW = "view"
+    TRIGGER_ANALYSIS = "trigger_analysis"
+    CLASSIFY = "classify"
+    WRITE_BACK = "write_back"
+    MANAGE_REPOSITORY = "manage_repository"
+    MANAGE_PROMPTS = "manage_prompts"
+    MANAGE_CREDENTIALS = "manage_credentials"
+    MANAGE_USERS = "manage_users"
+    VIEW_AUDIT_LOG = "view_audit_log"
+
+
+# 每个角色「新增」的权限；最终权限由 ROLE_PERMISSIONS 按层级累积
+_ROLE_GRANTS: dict[Role, frozenset[Permission]] = {
+    Role.VIEWER: frozenset({Permission.VIEW}),
+    Role.REVIEWER: frozenset({Permission.TRIGGER_ANALYSIS}),
+    Role.COMMITTER: frozenset({Permission.CLASSIFY, Permission.WRITE_BACK}),
+    Role.MAINTAINER: frozenset(
+        {
+            Permission.MANAGE_REPOSITORY,
+            Permission.MANAGE_PROMPTS,
+            Permission.VIEW_AUDIT_LOG,
+        }
+    ),
+    Role.ADMIN: frozenset(
+        {
+            Permission.MANAGE_CREDENTIALS,
+            Permission.MANAGE_USERS,
+        }
+    ),
+}
+
+
+def _build_role_permissions() -> dict[Role, frozenset[Permission]]:
+    """按层级累积权限：每个角色拥有自身及所有低角色的权限。"""
+    result: dict[Role, frozenset[Permission]] = {}
+    accumulated: set[Permission] = set()
+    for role in sorted(Role):
+        accumulated |= _ROLE_GRANTS[role]
+        result[role] = frozenset(accumulated)
+    return result
+
+
+ROLE_PERMISSIONS: dict[Role, frozenset[Permission]] = _build_role_permissions()
+
+
+def role_has_permission(role: Role | str, permission: Permission) -> bool:
+    if isinstance(role, str):
+        try:
+            role = Role[role.upper()]
+        except KeyError:
+            return False
+    if not isinstance(role, Role):
+        return False
+    return permission in ROLE_PERMISSIONS[role]

package/backend/app/core/queue.py

@@ -0,0 +1,57 @@
+"""任务队列投递。
+
+API 侧只负责"投递"，不关心谁执行 —— 定时轮询由 worker 的 cron 驱动，
+而手动触发的同步/分析走这里入队，避免在请求里长时间阻塞。
+
+队列不可用时投递失败必须降级而非报错：Web 界面不该因为 worker 没起来
+就打不开。降级会记 warning，且入队结果如实返回给调用方。
+"""
+
+from __future__ import annotations
+
+import structlog
+from arq import create_pool
+from arq.connections import ArqRedis, RedisSettings
+
+from app.core.config import Settings
+
+logger = structlog.get_logger(__name__)
+
+_pool: ArqRedis | None = None
+
+
+def redis_settings_from(settings: Settings) -> RedisSettings:
+    return RedisSettings.from_dsn(settings.valkey_url)
+
+
+async def get_pool(settings: Settings) -> ArqRedis | None:
+    """取队列连接池。Valkey 不可达时返回 None，由调用方决定如何降级。"""
+    global _pool
+    if _pool is not None:
+        return _pool
+    try:
+        _pool = await create_pool(redis_settings_from(settings))
+    except Exception as exc:
+        logger.warning("queue_pool_unavailable", error=str(exc))
+        return None
+    return _pool
+
+
+async def close_pool() -> None:
+    global _pool
+    if _pool is not None:
+        await _pool.aclose()
+        _pool = None
+
+
+async def enqueue(settings: Settings, function: str, *args, **kwargs) -> str | None:
+    """投递一个任务，返回 job_id；队列不可用时返回 None。"""
+    pool = await get_pool(settings)
+    if pool is None:
+        return None
+    try:
+        job = await pool.enqueue_job(function, *args, **kwargs)
+    except Exception as exc:
+        logger.warning("enqueue_failed", function=function, error=str(exc))
+        return None
+    return job.job_id if job is not None else None