# github-code-space

**Repository Path**: hefuhai001/github-code-space

## Basic Information

- **Project Name**: github-code-space
- **Description**: 一个仿 GitHub Codespaces 的在线代码编辑器 Demo，使用 Vite + React 18 + TypeScript 构建，界面复刻 GitHub 官方风格。支持编辑内置示例数据，也可以连接本地 Docker 容器，实时开发容器内的代码。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-11
- **Last Updated**: 2026-08-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GitHub Space

一个仿 **GitHub Codespaces** 的在线代码编辑器 Demo，使用 **Vite + React 18 + TypeScript** 构建，界面复刻 GitHub 官方风格。支持编辑内置示例数据，也可以**连接本地 Docker 容器**，实时开发容器内的代码。

## 功能

- **仓库列表页**（`/`）：GitHub 风格仓库卡片，支持按名称/描述/所有者搜索过滤
- **在线代码编辑工作区**（`/repo/:repoId`）：
  - 文件树浏览（目录展开/折叠，与 GitHub 一致的排序：目录在前）
  - 多标签页编辑（打开/关闭/切换，未保存内容有圆点标记）
  - CodeMirror 6 编辑器，按扩展名自动启用语法高亮（JS/TS/JSX/HTML/CSS/JSON/Markdown/Python/C/C++）
  - 路径面包屑 + 状态栏（分支、文件数、光标行列、保存状态）
  - `Ctrl+S` 或「保存」按钮保存修改
  - 新建文件（在侧边栏内联输入）
  - 分支选择、Star/Fork 按钮（本地状态）
- **连接 Docker 容器开发**：
  - Header 中「连接服务器」→ 选择运行中的容器 + 工作目录，工作目录下的子目录映射为仓库列表
  - 文件树/编辑/保存**实时读写容器内文件**（`docker cp` 语义，二进制安全）
  - **简易交互终端**：进入 Docker 仓库时**自动打开**，并**定位到当前仓库目录**（如 `/workspace/hello-node`），可直接 `npm start` 运行项目；WebSocket 桥接容器内持久 shell，`cd` 等状态跨命令保留
  - 连接/断开即时切换回内置示例数据

## 快速开始

```bash
npm install
npm run dev:all   # 同时启动前端(Vite:5173) + 后端(Node:3001)，推荐
# 或分别启动：
npm run dev       # 仅前端
npm run server    # 仅后端
npm run build     # 类型检查 + 生产构建
npm run test      # 单元测试（Vitest）
npm run lint      # 静态检查（Oxlint）
```

### 连接 Docker 容器的前置条件

1. 本机有可用的 Docker daemon（Docker Desktop 或 WSL2 中的 Docker）
2. 启动后端时后端默认连接 `tcp://127.0.0.1:2375`（Windows + WSL2 转发场景），可用环境变量覆盖：`DOCKER_HOST=tcp://<host>:<port> npm run server`
3. 准备一个开发容器（如 `docker run -d --name gs-dev -w /workspace node:22 node -e "setInterval(()=>{},1e9)"`），并把代码放进工作目录
4. 打开 http://localhost:5173 → Header「连接服务器」→ 选择容器 + 工作目录 → 连接

## 架构

```
浏览器（React 前端）
  │  HTTP/WS（开发期经 Vite 代理 /api，生产期后端直接托管 dist，同源）
  ▼
Node 后端（server/，Express + dockerode + ws，端口 3001，仅绑定 127.0.0.1）
  │  Docker API（docker exec / docker cp）
  ▼
本地 Docker 容器（用户已有容器，如 node:22-alpine）
```

```
src/
├── types/                # Repository、FileNode、OpenFile 等类型
├── data/mockRepos.ts     # 内置 4 个示例仓库（文件树 + 文件内容）
├── services/
│   ├── workspace.ts      # WorkspaceService 接口（数据访问抽象层）
│   ├── mockService.ts    # Mock 实现：localStorage 持久化，刷新不丢数据
│   ├── dockerService.ts  # Docker 实现：实时读写容器内文件
│   ├── dockerConnection.ts # 连接配置（localStorage + 订阅）
│   ├── githubService.ts  # 预留的 GitHub API 实现骨架（标注 TODO）
│   └── index.ts          # getWorkspaceService() 工厂（按连接状态切换）
├── utils/                # 语言映射、文件树工具
└── components/
    ├── Header.tsx        # GitHub 风格顶栏（含搜索 + 连接服务器入口）
    ├── DockerConnect.tsx # 容器连接弹窗
    ├── RepoListPage.tsx  # 仓库列表页
    └── workspace/        # RepoHeader / FileTree / EditorTabs / CodeEditor /
                          # Breadcrumb / StatusBar / TerminalPanel
server/
├── index.js              # Express 入口 + WS 升级 + 静态托管 dist
├── routes.js             # /api 路由
├── dockerClient.js       # dockerode 客户端（DOCKER_HOST 可配）
├── repos.js              # 仓库/文件操作（find 树 + docker cp 读写）
├── exec.js               # 容器内命令执行（非交互）
├── terminal.js           # 交互终端会话（WS ↔ dockerode 流桥接）
└── util.js               # shell 转义与路径安全校验
```

## 数据层与切换

所有数据访问都通过 `WorkspaceService` 接口，工厂按状态自动选择实现：

| 实现 | 何时生效 | 说明 |
| --- | --- | --- |
| `MockWorkspaceService` | 未连接容器 | 内置示例数据 + localStorage 持久化 |
| `DockerWorkspaceService` | 已连接容器 | 实时读写容器内文件，配合交互终端 |
| `GitHubWorkspaceService` | `VITE_USE_GITHUB_API=true` | 预留骨架，需补全实现并配置 Token |

## 安全说明

- 后端**仅绑定 127.0.0.1**，且会在你选择的容器内执行任意命令（文件读写、终端）——请勿暴露到公网或绑定 0.0.0.0
- 所有拼进 `sh -c` 的容器命令都经过 POSIX 引号转义，仓库名/文件路径经过路径穿越校验

## 技术栈

| 领域 | 选型 |
| --- | --- |
| 脚手架 / 构建 | Vite 8 + TypeScript |
| UI | React 18 + React Router 7 |
| 代码编辑器 | CodeMirror 6（@uiw/react-codemirror + 语言包） |
| 终端 | xterm.js（@xterm/xterm + fit，完整解析 ANSI/spinner） |
| 样式 | Tailwind CSS v4（GitHub 调色板 theme tokens，仅保留约 90 行入口 CSS） |
| 后端 | Express 5 + dockerode + ws（Node 22+，纯 ESM） |
| 测试 | Vitest + Testing Library + happy-dom |