# compiler

**Repository Path**: jimonik/compiler

## Basic Information

- **Project Name**: compiler
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-01
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 编译流水线

仓库地址：<https://gitee.com/jimonik/compiler.git>

## 作为控制面板插件

面板入口为 `panel_plugin.py`，导出 `create_app(context)`，直接复用 FastAPI 应用并挂载在 `/plugins/compiler/`。插件模式不调用本仓库的 `main.py`，因此不会监听 `8765` 或任何独立端口；局域网设备只访问控制面板的 `8000` 端口。

仓库根目录的 `panel-plugin.json` 是插件身份清单。使用者只需在面板底部选择本仓库文件夹，面板会自动识别、加入并启用，不需手写配置。

插件依赖见 `requirements.txt`，由面板 Python 环境统一安装。运行数据仍位于本仓库 `data/`。前端 API、静态资源和 WebSocket 已兼容 `/plugins/compiler/` 挂载前缀。验证命令为 `python3 -m compileall app panel_plugin.py`。

插件接收本体发送的 `lan-panel-theme` 消息并支持 `light`、`dark` 两种主题，不自行跟随系统主题。

本地 Web 工具：管理多个 Git 仓库、配置编译环境并执行自定义编译命令。文件浏览、预览、移动、删除和下载统一由文件管理器插件负责。

默认在浏览器打开 `http://127.0.0.1:8765` 使用。

## 环境要求

| 依赖 | 说明 |
|------|------|
| Python | 3.10+ |
| Git | 用于克隆、拉取、切换分支 |
| 编译工具链 | 按项目需要自行安装（Flutter、JDK、Android SDK、Gradle 等） |

服务进程会继承当前 shell 的系统环境变量；页面里「已启用的环境」会额外注入到编译命令执行环境中。

## 安装

```bash
cd /path/to/compiler
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

## 启动

```bash
python3 main.py
```

启动后会自动释放占用端口（默认 `8765`），并打印本机与局域网访问地址。

### 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `COMPILER_HOST` | `0.0.0.0` | 监听地址；仅本机访问可设为 `127.0.0.1` |
| `COMPILER_PORT` | `8765` | 监听端口 |

示例：

```bash
COMPILER_HOST=127.0.0.1 COMPILER_PORT=9000 python3 main.py
```

## 快速上手

1. 点击左侧 **+ 新建**，填写仓库名称和 Git 地址。
2. 在「仓库配置」中点击 **获取分支**，选择目标分支后 **保存**。
3. 点击 **克隆**，将代码拉到本地（`data/repos/<仓库ID>/`）。
4. 在「环境配置」中从 **已知环境** 启用编译所需变量（如 `FLUTTER_BIN`、`JAVA_HOME`、`ANDROID_HOME`）。
5. 在「编译配置」填写 **工作目录** 和 **编译命令**（每行一条），点击 **保存** 后 **编译**。
6. 构建完成后到控制面板的「文件管理器」插件管理或下载产物。

## 功能说明

### 仓库管理

- **保存**：写入 Git 地址、分支、账号等配置到 `data/repos.json`。
- **克隆**：首次将远程仓库克隆到本地；若未克隆，点编译时会自动尝试克隆。
- **更新代码**：执行 `git reset --hard && git pull`，**本地未提交修改会丢失**，操作前请确认。
- **克隆与切换分支**：新仓库会完整获取所有远程分支，并检出所选分支。仓库已克隆时，在仓库配置中选择分支会立即切换本地工作区；旧版创建的浅克隆或单分支仓库会在首次切换时自动补全历史和全部远程分支。如存在冲突或正在编译，会恢复原选择并显示错误。仓库尚未克隆时，选择结果会保存并在克隆时生效。
- **删除**：删除仓库配置与本地目录；若正在编译，会先终止编译任务。
- **切换仓库**：切换前会自动保存当前仓库的编译配置和仓库配置；各仓库配置相互独立。

左侧列表悬停可点 **×** 快速删除；正在编译的仓库会显示「编译中」状态。

### 环境配置

编译命令通过 `${变量名}` 引用环境，例如：

```text
${FLUTTER_BIN} pub get
${FLUTTER_BIN} build apk --release
```

**已知环境** 会自动扫描本机：

- 系统环境变量（`JAVA_HOME`、`ANDROID_HOME`、`FLUTTER_ROOT` 等）
- `which` 找到的可执行文件（`FLUTTER_BIN`、`GRADLE_BIN` 等）
- 常见 JDK / Android SDK / FVM / Flutter 安装路径

同一目标变量（如 `JAVA_HOME`）若有多个候选，会以分组形式展示，**选一个启用**即可。

**手动添加环境**：可加入自定义路径，并可用测试命令验证（如 `${DART_BIN} --version`）。

**已启用的环境** 按仓库单独保存；切换仓库后各自保留，不会互相覆盖。

> 编译前会校验：命令里出现的 `${变量}` 必须已在「已启用的环境」中配置，否则会提示缺失变量。

### 编译

- **多套配置**：每个仓库可以创建任意数量的命名编译配置，例如 `dev`、`prod`。配置以列表展示，每套配置独立保存名称、编译分支、工作目录和 Shell 命令，并可直接从所在行发起编译。点击编译后界面会自动切换到编译日志，仓库未克隆时会先完整克隆对应分支。
- **新增、编辑与删除**：点击「新增」创建配置，点击编辑图标在居中弹窗内修改名称和命令；除最后一套配置外均可删除。旧版本的单一编译配置会自动迁移为名为「默认」的配置。
- **工作目录**：相对于克隆后的仓库根目录，`.` 表示根目录。
- **编译命令**：按顺序逐条在 shell 中执行；stdout/stderr 实时输出到「编译日志」。
- **后台编译**：切换到其他仓库不会中断当前编译；后台任务会继续运行，列表仍显示「编译中」，切回该仓库可继续看日志。
- **终止编译**：编译期间按钮会变为「终止编译」；点击后会终止当前命令及其子进程，适用于命令等待用户输入等无法自行结束的情况。
- **清空**：仅清空页面上的日志显示，不影响服务端记录。

### 文件职责边界

编译器只负责 Git、环境、终端和构建过程，不再提供通用文件浏览及下载接口。构建产物与其他文件统一交给文件管理器插件处理，避免两套文件操作逻辑产生不同的权限和行为。

## 配置示例

### Flutter 项目

工作目录：`.`

```text
${FLUTTER_BIN} pub get
${FLUTTER_BIN} build apk --release
```

启用环境：`FLUTTER_BIN`（或从 FVM 候选中选择对应 SDK）

产物常见路径：`build/app/outputs/flutter-apk/`

### Android / Gradle 项目

工作目录：`.` 或子模块目录

```text
chmod +x gradlew
./gradlew assembleRelease
```

启用环境：`JAVA_HOME`、`ANDROID_HOME`

产物常见路径：`app/build/outputs/apk/release/`

## 数据目录

| 路径 | 内容 |
|------|------|
| `data/repos.json` | 各仓库配置（Git 信息、编译命令、已启用环境等） |
| `data/env_library.json` | 全局「手动添加」的已知环境 |
| `data/repos/<ID>/` | 克隆下来的 Git 工作区 |

删除仓库会同时移除对应配置项与 `data/repos/<ID>/` 目录。

## 常见问题

**获取分支失败**

- 检查 Git 地址是否正确。
- 私有仓库需填写用户名和密码/Token。
- 确认本机可访问该 Git 远程（网络、VPN、SSH/HTTPS 权限）。

**编译提示「未启用的环境变量」**

- 在「已知环境」中找到对应项并 **启用**，或手动添加后启用。
- 变量名须为大写字母、数字、下划线，且以字母开头。

**编译命令找不到工具**

- 确认已在「已启用的环境」中配置了正确路径。
- 服务启动时的 shell 环境也会影响 `which` 检测结果；必要时用手动添加补全路径。

**局域网其他设备无法访问**

- 确认 `COMPILER_HOST=0.0.0.0`（默认）。
- 检查防火墙是否放行 `COMPILER_PORT`。
- 编译在本机执行，远程浏览器仅操作界面，实际仍使用**运行服务的那台机器**上的工具链。

## 项目结构

```text
compiler/
├── main.py              # 入口，启动 uvicorn
├── requirements.txt
├── app/
│   ├── main.py          # FastAPI 路由与 WebSocket
│   ├── build_runner.py  # 编译任务执行
│   ├── git_manager.py   # Git 克隆/拉取/分支
│   ├── env_detector.py  # 本机环境自动检测
│   ├── env_service.py   # 环境面板数据
│   ├── storage.py       # 仓库配置持久化
│   └── ...
├── static/              # Web 前端
└── data/                # 运行时数据（配置与克隆目录）
```