gopan

gopan

简体中文 · English

自部署云盘。Go + GraphQL + Postgres + MinIO 后端,单二进制交付,2 核 2G 的 VPS 就能跑。三个客户端:Vue 3 网页、Kotlin + Jetpack Compose 的安卓原生 App、Windows 桌面端(Tauri)。

• 内置 AI 助手:网页、桌面端、安卓 App 里都能用,找文件、读文档、整理、建分享;改动先确认,也能整轮交给服务器跑。
• 自带 Remote MCP:Claude、ChatGPT、Codex 等 Agent 经 OAuth 2.1 接入,在你授权的范围里找、读、整理、分享网盘里的文件;文件字节不经过 MCP,Agent 做的每次改动都能在「动态」里按来源撤回。各客户端怎么接见 docs/MCP.md · 客户端接入,给 Agent 的用法说明见 Agent Skill。

[CI]

在线实例:https://drive.979687.xyz(跑在 2 核 2G 的 VPS 上,精简档部署)

当前版本与每一版改了什么见 CHANGELOG(站点的 /app 页面与 App 的「更新日志」展示的就是它);功能全貌见 12 · 产品说明。

架构

flowchart LR    Browser["浏览器 · Vue 3 SPA"]    Browser -- "GraphQL /query<br/>(元数据与编排)" --> GQL    Browser <-. "字节流:预签名 URL<br/>分片直传 / 直取" .-> MinIO    Android["安卓 App · Compose"] -- "GraphQL /query" --> GQL    Android <-. "预签名直传 / 直取<br/>(后台续传)" .-> MinIO    Agent["Agent · MCP Host"] -- "Streamable HTTP /mcp<br/>OAuth 2.1 / API Key" --> MCP    Agent <-. "预签名 PUT / GET<br/>Agent 自主传输" .-> MinIO    DAV["Finder · rclone · WebDAV 客户端"] -- "WebDAV /dav<br/>应用密码" --> REST
    subgraph Gopan["gopan · Go 单二进制"]        GQL["gqlgen"] --> Service["service 业务层"]        MCP["Remote MCP · OAuth server"] --> Service        REST["HTTP:/dav · /pack · /arc · /x/:token · /sub · /md · /api/img · /s/:token · /api/app · /healthz"] --> Service        Worker["worker pool<br/>缩略图 · 转 PDF · hash 校验 · 文字提取 · 压缩包目录 · GC"]        Jobs["后台任务 runner<br/>离线下载 · 解压 · 剪藏 · 订阅"]        Embed["embed 前端静态资源"]    end
    Service --> PG[("PostgreSQL<br/>元数据 · 事务 · 递归 CTE")]    Service --> MinIO[("MinIO<br/>blobs/{sha256} 内容寻址")]    Worker --> MinIO    Worker --> GT["Gotenberg<br/>(office → PDF,可关)"]    Worker --> FF["ffmpeg(exec)"]    Worker --> PT["pdftotext(exec)"]    Jobs --> MinIO    Jobs -. "离线下载 · 订阅 · 剪藏(挡内网)" .-> Web(("外部网站"))    Service -. "推送(挡内网)" .-> Push(("ntfy · Bark · Telegram · Webhook"))

要点:主传输路径字节流不过 Go——浏览器、安卓 App 和 Agent 都拿预签名 URL 直传/直取 MinIO。显式例外只有流式 zip(/pack、/mcp-download)、协议决定必须中转的 WebDAV PUT/GET、几 MB 的安卓安装包(/api/app/android/),v3.3 的离线下载(服务器替你从源站拉)与压缩包(解压、/arc 预览包里的单个文件),以及 v3.4 的直链(/x/,经 Go 才能记流量、按上限拦、吊销即时生效)、图床上传与字幕转换,都有并发闸。文件按 SHA-256 内容寻址,全站同内容物理只存一份(秒传),配额按逻辑大小各记各的。类型从数据库到组件不断链:sqlc(SQL→Go)、gqlgen(schema→resolver)、GraphQL Code Generator(schema→TS),改一处两端编译报错。

快速开始

部署(用预构建镜像)

一台有公网 IP 的 Linux 主机(2G 内存够用)、一个解析到它的域名、Docker 与 compose 插件。镜像由 GitHub Actions 构建,机器上不编译(只有 linux/amd64):

git clone https://github.com/yophon/gopan.git /opt/gopan && cd /opt/gopancp .env.example .env && vi .env    # 填域名与两个密码,选部署档位,取消 GOPAN_IMAGE 的注释mkdir -p secrets && openssl rand -base64 48 > secrets/jwt_secretchown 10001:10001 secrets/jwt_secret && chmod 400 secrets/jwt_secret && chmod 600 .envdocker compose -f docker-compose.prod.yml pulldocker compose -f docker-compose.prod.yml up -d --no-build

选档(自带 Caddy 自动证书,还是交给宿主 nginx)、反代约定、升级、备份与恢复、排障都在 09 · 上线手册。

开发

make dev-env      # compose 起 postgres/minio/gotenbergmake dev-server   # 后端 :8080(自动跑迁移)make dev-web      # 前端 :5173(proxy → 8080)
make gen          # 改了 schema.graphqls / db/queries 后重新生成三件套make test         # go test + vet(集成测试需 TEST_DB_URL)make build        # 前端构建 + embed → server/gopan 单二进制

生产运行只需要 server/gopan 二进制 + GOPAN_DB_URL + GOPAN_JWT_SECRET(≥32 字节),配置项见 doc/08。

安卓 App 与桌面端连哪个站点是打包时定的:照 client.env.example 在仓库根建 client.env(不进 git)写上自己实例的地址,两端都读它(doc/18「自部署」)。

设计文档

浏览器上传的 staging 隔离、配额复核、失败恢复和升级兼容说明见 15 · 上传一致性修复。

Agent 接入与远程 MCP 工具见 docs/MCP.md(各客户端的接法在客户端接入一节),给 Agent 的用法说明见 skills/gopan/。

全部设计文档在 doc/:

实现回顾

每个里程碑实际交付了什么、关键决策、踩坑记录,在 doc/milestones/。v3.5 之后各版本的设计与取舍写在 doc/24 起的各篇文档里(上表),逐版的变化见 CHANGELOG:

读法

想看全貌:01 → 02 → 03,或者直接读 12(产品说明,一页版)。要动手:04、05 是数据库与 GraphQL 合同,MCP 的协议合同单独见 docs/MCP.md。想知道每步实际怎么落地的:doc/milestones/。要部署:doc/09 照着走,装新机前先扫一遍 doc/10 的检查清单。只是用:doc/11 使用手册;安卓 App 看 doc/18;每个版本改了什么看 CHANGELOG(站点上是 /app)。

许可证

MIT。web/src/vendor/tau/ 是 tau 的编译产物,同样是 MIT。