Codespace 一体机设计文档

本仓库用于记录 Codespace 一体机（物理机 + 虚拟化 + K3S 服务栈）的设计与部署方案。

文档目录

• 架构与组成
• K3S 虚拟机安装
• PostgreSQL 安装
• Keycloak 安装与配置
• OAuth2-Proxy 安装
• Codespace 命名空间与动态路由
• Codespace 镜像构建
• LiteLLM 部署
• Hindsight 部署
• Forgejo 安装与 OpenID 认证

一体机设计总览

一个 Codespace 一体机由以下部件组成：

• 虚拟化底座
• K3S 虚拟机
  • OAuth2-Proxy
  • Keycloak
  • Codespace（含 VSCode）
  • Forgejo（Git 服务器）
  • Hindsight
  • LiteLLM
• PostgreSQL 虚拟机
• 测试用虚拟机

推荐阅读顺序

1. 先看架构与组成，确认整体拓扑。
2. 完成 K3S 底座部署。
3. 部署 PostgreSQL 与 Keycloak。
4. 配置 OAuth2-Proxy 与 Codespace 动态路由。
5. 构建并发布 Codespace 工作区镜像。
6. 部署 LiteLLM（模型网关）。
7. 部署 Hindsight（记忆服务）。
8. 部署门户服务（Portal）并打通统一认证入口。
9. 部署 Forgejo 并对接 Keycloak OpenID。

文档说明

• 本 README 聚焦一体机设计与阅读导航。
• 研发流程相关内容放在文末“开发维护（可选）”章节。

开发维护（可选）

全局 Git Hook 自动格式化

如果希望这台机器上的 Git 仓库在提交前自动格式化，可以通过全局 core.hooksPath 启用。

准备全局 Hook 目录

mkdir -p ~/.githooks
git config --global core.hooksPath ~/.githooks

创建 pre-commit Hook

将以下内容追加到 ~/.githooks/pre-commit（可与现有脚本合并）：

#!/bin/bash

require_formatter() {
    local cmd=$1
    local label=$2
    local files=$3

    if ! command -v "$cmd" >/dev/null 2>&1; then
        echo -e "\n\033[31m[错误] 缺少必需的格式化命令：$cmd\033[0m"
        echo "已暂存的 $label 文件必须先用 $cmd 格式化后才能提交。"
        echo "受影响文件："
        printf '%s\n' "$files" | sed 's/^/  - /'
        exit 1
    fi
}

echo "运行代码格式化..."
# 仅获取新增或修改的文件 (排除删除的文件)
FORMAT_FILES=$(git diff --cached --name-only --diff-filter=ACM)

if [ -n "$FORMAT_FILES" ]; then
  PY_FILES=$(echo "$FORMAT_FILES" | grep '\.py$' || true)
  MD_FILES=$(echo "$FORMAT_FILES" | grep '\.md$' || true)
  SH_FILES=$(echo "$FORMAT_FILES" | grep '\.sh$' || true)

  if [ -n "$PY_FILES" ]; then
    echo "  > 正在格式化 Python 脚本..."
    require_formatter "ruff" "Python" "$PY_FILES"
    echo "$PY_FILES" | xargs ruff format
    echo "$PY_FILES" | xargs git add
  fi

  if [ -n "$MD_FILES" ]; then
    echo "  > 正在格式化 Markdown 文档..."
    require_formatter "prettier" "Markdown" "$MD_FILES"
    echo "$MD_FILES" | xargs prettier --write
    echo "$MD_FILES" | xargs git add
  fi

  if [ -n "$SH_FILES" ]; then
    echo "  > 正在格式化 Shell 脚本..."
    require_formatter "shfmt" "Shell" "$SH_FILES"
    echo "$SH_FILES" | xargs shfmt -w -i 4
    echo "$SH_FILES" | xargs git add
  fi
fi

添加执行权限

chmod +x ~/.githooks/pre-commit

安装依赖格式化工具

pip install ruff
npm install -g prettier
apt install -y shfmt