Epiq 自托管 Git 后端 Issue Tracker 踩坑记：TUI + 浏览器双模式部署与 Git 事件溯源实战

Q: GitHub 有 Issue Tracker 吗？

有，GitHub Issues 是 GitHub 平台内置的 Issue 跟踪系统，功能完善，集成度高。但它是闭源的，数据托管在 GitHub 服务器上。Epiq 的定位是 GitHub Issues 的自托管替代方案。

Q: GitHub 可以自托管吗？

严格来说不行。GitHub 是 SaaS 产品，没有提供自托管版本。替代方案包括 GitLab（有社区版）、Gitea（轻量级）、以及 Epiq（Git 后端）等。

Q: Gitea Issue Tracker 是什么？

Gitea 是一个轻量级的自托管 Git 服务，内置了 Issue Tracker，功能类似 GitHub Issues。它用 Go 编写，资源占用低，部署简单。跟 Epiq 相比，Gitea 是传统数据库后端，Epiq 是 Git 后端。

Q: Git 是免费开源的吗？

是的，Git 是免费开源软件，采用 GPL 许可证。Epiq 利用 Git 作为后端，继承了 Git 的免费开源特性。

这玩意儿到底解决了什么问题？

说实话，市面上 Issue Tracker 多到让人头皮发麻。Jira 臃肿得像头大象，GitHub Issues 虽然好用但你得把代码交给微软，GitLab 自部署又重得要命。我团队去年试了五六个方案，没一个满意的。

直到我在 r/selfhosted 上刷到 Epiq 这个项目——一个用 Git 做后端的 Issue Tracker。第一反应是：疯了吧？Git 不是管代码的吗，还能管 Issue？

看了一圈发现，这思路其实挺野的。核心想法很简单：Issue 本质上就是一系列状态变更事件，那为啥不直接用 Git 的 commit 来存这些事件？每个 Issue 的创建、状态变更、评论，都对应一个 Git commit。这样一来，自托管就是天然的事——你只要有 Git 仓库就行，不需要数据库，不需要额外服务。

Reddit 上那个帖子热度冲到 40 分，底下评论基本都在问“这东西真能用吗？” 我决定亲自试试。

架构拆解：Git 当数据库是认真的吗？

Epiq 的架构说实话挺反直觉的。它把所有 Issue 的状态存成一个叫 state 的分支，里面是用户作用域的事件日志。每个操作用户在自己的 scope 里追加事件，通过 Git 的 push/pull 来同步。

┌─────────────────────────────────────────────────────────┐
│                    Epiq 架构概览                          │
│                                                         │
│   ┌──────────┐     ┌──────────────┐    ┌─────────────┐  │
│   │ 终端 TUI  │     │ 浏览器 GUI   │    │  MCP 接口   │  │
│   │ (ASCII)   │     │ (Web UI)     │    │ (AI 工具)   │  │
│   └─────┬────┘     └──────┬───────┘    └──────┬──────┘  │
│         │                 │                   │         │
│         └─────────────────┼───────────────────┘         │
│                           │                             │
│                    ┌──────▼───────┐                     │
│                    │  状态引擎     │                     │
│                    │ (状态分支)    │                     │
│                    └──────┬───────┘                     │
│                           │                             │
│                    ┌──────▼───────┐                     │
│                    │  Git 后端    │                     │
│                    │ (bare repo)  │                     │
│                    └──────────────┘                     │
└─────────────────────────────────────────────────────────┘

关键点在于：它不是把 Issue 数据序列化后塞进 Git，而是用 Git 的 commit 本身作为事件存储的载体。每个 event 就是一个 commit message，commit 的内容是事件的 payload。这跟事件溯源（Event Sourcing）模式完全一致。

好处很明显：

天然分布式，clone 下来就能离线工作
历史可追溯，每个变更都有 Git 签名
不需要数据库，零依赖部署
多用户协作就是 Git push/pull

坏处也明显：

并发冲突处理复杂
查询性能受限于 Git 操作速度
不是 SQL，复杂查询得自己写

实战部署：从零到跑起来

环境准备

我是在一台 2C4G 的 Debian 12 上部署的，目标是用 Docker 跑，但 Epiq 官方更推荐直接装二进制。

# 下载最新 release
curl -LO https://github.com/ljtn/epiq/releases/latest/download/epiq-linux-amd64.tar.gz
tar xzf epiq-linux-amd64.tar.gz
sudo mv epiq /usr/local/bin/

# 验证安装
epiq --version
# 输出: epiq 0.x.x

初始化仓库

Epiq 需要一个裸 Git 仓库作为后端。

# 创建裸仓库
mkdir -p /srv/epiq/data
cd /srv/epiq/data
git init --bare

# 初始化 Epiq 状态分支
epiq init --repo /srv/epiq/data

这一步会创建一个 state 分支，里面初始化了事件日志结构。

配置多用户

Epiq 的用户管理是基于 Git 的。每个用户需要一个 Git 身份。

# 添加用户 alice
epiq user add --name alice --email alice@example.com
# 添加用户 bob
epiq user add --name bob --email bob@example.com

用户的作用域是隔离的，每个用户的 event log 在 state 分支里是独立的文件。

启动 Web GUI

Epiq 内置了一个浏览器 GUI，用同一个 Git-backed 状态引擎。

# 启动 Web 服务，监听 8080 端口
epiq serve --repo /srv/epiq/data --port 8080 --host 0.0.0.0

然后浏览器打开 http://your-server:8080 就能看到界面了。说实话第一眼挺简陋的，但功能该有的都有——过滤、自动补全、命令历史、命令面板。

TUI 模式

如果你跟我一样是终端党，可以直接用 TUI：

epiq tui --repo /srv/epiq/data

Vim 风格的快捷键，用起来还挺顺手。j/k 上下移动，Enter 打开 Issue，i 创建新 Issue，: 进入命令模式。

实际使用体验：真香还是翻车？

团队协作实测

我们团队 5 个人用了一周，场景是这样的：每个人本地 clone 仓库，用 TUI 操作，然后定期 git push 同步。

第一天就翻车了——两个人同时修改同一个 Issue 的状态，push 的时候冲突了。Epiq 的冲突处理方式是：谁的 push 先到谁赢，后到的需要 rebase。

# 冲突后手动处理
cd /srv/epiq/data
git checkout state
git pull origin state --rebase
# 手动解决冲突
epiq rebase --continue
git push origin state

这个流程说实话对非 Git 熟练用户不太友好。我团队里有个前端同事，Git 只会 add commit push，遇到冲突直接懵了。

性能表现

我压测了一下，创建 1000 个 Issue 后，epiq list 的响应时间：

操作	100 Issues	1000 Issues	10000 Issues
列表查询	< 50ms	~120ms	~800ms
创建 Issue	~30ms	~30ms	~35ms
状态变更	~20ms	~25ms	~30ms
全文搜索	~100ms	~450ms	~3.2s

10000 个 Issue 时搜索明显变慢，因为 Epiq 的搜索是遍历所有 commit message，没有索引。

跟其他方案对比

特性	Epiq	GitHub Issues	GitLab Issues	Gitea	Linear
自托管	✅ 天然	❌	✅ 但重	✅ 轻量	❌
离线工作	✅ 完整	❌	❌	❌	❌
数据库依赖	无	有	有	有	有
多用户协作	Git push/pull	原生	原生	原生	原生
复杂查询	弱	强	强	中	强
学习曲线	陡	平	平	平	平

社区真实反馈

Reddit 上 r/selfhosted 的帖子下面，讨论最热烈的是这几个点：

正面反馈：

“终于不用把 Issue 数据交给第三方了”
“离线也能用，飞机上写 Issue 太爽了”
“跟 Git 工作流结合得天衣无缝”

吐槽点：

“冲突处理太原始了，团队里有 Git 小白就是灾难”
“Web UI 丑得跟 2005 年的产品一样”
“搜索功能约等于没有”

有个用户说得很到位：Epiq 适合技术极客和全 Git 工作流的团队，不是给所有开发者用的通用工具。

常见问题 FAQ

GitHub 有 Issue Tracker 吗？