# webpan

**Repository Path**: chen-superplus/webpan

## Basic Information

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

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# zky-webpan

基于 **Go** 的轻量个人网盘。支持 **S3 兼容对象存储**、**WebDAV** 与 **Telegram** 三种存储后端，并提供基于 Telegram 的**文件中转站**。提供文件浏览、上传下载、带提取码的分享功能。

## 特性

- **多存储后端**：支持多个 S3、多个 WebDAV 和 Telegram，可在运行时切换
- **Telegram 存储**：文件内容保存在 Telegram 消息中，本地仅保存元数据，不占用本地磁盘
- **文件中转站**：无需登录即可上传，生成分享码和 4 位提取码，默认 7 天有效并自动清理
- **便捷取件**：我的上传记录持久显示提取码，复制链接时可自动携带提取码
- **上传体验**：网盘和中转站均显示上传进度；请求完成前的 Telegram 处理阶段显示“处理中”
- **SOCKS5 代理**：Telegram 通过容器内 mihomo 解析 Clash 订阅并连接本地 SOCKS5，自动选优和切换节点，支持代理测试
- **离线资源采集**：提交下载链接，服务器后台自动下载并上传到指定存储空间，可设置多个任务顺序执行，关闭网页后仍继续运行，可随时回来看执行结果
- **文件管理**：目录浏览、多文件上传下载、新建文件夹、删除、分享和图片直链
- **分享**：单文件 / 文件夹分享，支持提取码与 1/7/30 天或永久有效期
- **轻量**：单二进制部署，无前端构建步骤；也支持 Docker 一键部署
- **单管理员认证**：密码登录 + 会话管理，会话默认 24 小时

## 技术栈

| 组件 | 选择 |
|------|------|
| 语言 | Go 1.25（标准库 `net/http`，无 Web 框架）|
| 存储 | S3（`minio-go`）、WebDAV、Telegram（`gotd/td` MTProto）|
| 元数据 | bbolt（分享记录）+ SQLite（Telegram 元数据 / 中转记录 / 离线任务）|
| 前端 | 原生 HTML/CSS/JS，`go:embed` 嵌入，零构建 |
| 配置 | YAML（`yaml.v3`）|

## 目录结构

```
zky-webpan/
├── main.go                    # 入口，路由注册，静态资源
├── config.yaml                # 配置文件
├── internal/
│   ├── config/                # 配置加载
│   ├── auth/                  # 认证（密码 + 内存 session）
│   ├── storage/               # S3 / WebDAV / Telegram 存储封装
│   ├── telegram/              # Telegram MTProto 客户端 + 代理管理
│   ├── transfer/              # 文件中转站（SQLite + Telegram）
│   ├── offline/               # 离线资源采集（SQLite + 后台顺序 worker）
│   ├── share/                 # 分享记录（bbolt）
│   └── handler/               # HTTP 处理器
└── web/
    ├── login.html             # 登录页
    ├── index.html             # 文件管理主界面
    ├── share.html             # 分享访问页
    ├── transfer.html          # 文件中转站
    ├── offline.html           # 离线资源采集
    └── static/style.css       # 统一样式
```

## 快速开始

### 方式一：Docker 部署（推荐）

项目已将网盘与 mihomo 打包，Telegram 只需连接容器内的本地 SOCKS5，S3/WebDAV 默认直连。

```bash
cd docker
cp .env.example .env
# 编辑 .env，至少填写订阅链接、BOT_TOKEN、CHAT_ID 和 ADMIN_PASSWORD
# 国内服务器通常使用 GLOBAL；国外服务器如只需 Telegram 走代理可使用 DIRECT
docker compose up -d --build
```

默认访问 `http://localhost:8080`。如需使用 `5600` 端口，在 `docker/.env` 设置 `WEBPAN_PORT=5600`。mihomo 控制 API 默认映射到 `9090`，仅在需要面板或调试时开放。详细说明见 [`docker/README.md`](docker/README.md)。

### 方式二：直接编译运行

复制配置模板并填入你的存储信息：

```bash
cp config.example.yaml config.yaml
```

编辑 `config.yaml` 后编译运行：

```bash
# 国内网络可按需设置代理
go env -w GOPROXY=https://goproxy.cn,direct

go build -o zky-webpan .
./zky-webpan -c config.yaml
```

启动后访问 `http://localhost:8080`，使用配置中的登录密码进入。

### 交叉编译（部署到 Linux/NAS）

```bash
# 编译 Linux amd64 版本
GOOS=linux GOARCH=amd64 go build -o zky-webpan .

# 编译 ARM（树莓派 / 群晖）
GOOS=linux GOARCH=arm64 go build -o zky-webpan .
```

部署时只需 `zky-webpan` 二进制 + `config.yaml` 两个文件。

## 配置说明

| 字段 | 说明 | 默认值 |
|------|------|--------|
| `server.addr` | 监听地址 | `:8080` |
| `s3.endpoint` | S3 endpoint | 必填 |
| `s3.access_key` / `secret_key` | S3 凭证 | 必填 |
| `s3.bucket` | 桶名 | 必填 |
| `s3.region` | S3 区域（CSTCloud 不校验） | `us-east-1` |
| `s3.use_ssl` | 是否 HTTPS | `true` |
| `tg.api_id` / `api_hash` | Telegram API 凭证 | 可选（留空用内置默认值）|
| `tg.bot_token` | Bot Token | 必填（用 Telegram 时）|
| `tg.chat_id` | 目标聊天 ID | 必填（用 Telegram 时）|
| `tg.proxies` | SOCKS5 代理列表（自动切换） | 由 Docker 内 mihomo 提供 `127.0.0.1:7891` |
| `tg.proxy_url` | 程序侧代理获取 API（已停用） | 空 |
| `tg.session_file` | MTProto 会话文件 | `./data/tg.session` |
| `tg.part_size` | Telegram 上传分片大小（字节） | `524288` |
| `tg.max_file_size` | Telegram / 中转站单文件上限（字节，最大 2GB） | `2147483648` |
| `auth.password` | 登录密码 | 必填 |
| `auth.session_ttl` | 会话有效期（秒） | `86400` |
| `data.db` | 分享记录数据库路径 | `./data/webpan.db` |
| `base_url` | 分享链接前缀，留空自动用请求 Host | 空 |

## API 一览

**公开接口**

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/login` | 登录，`{"password":"..."}` |
| GET | `/api/share/info?code=` | 查询分享信息 |
| POST | `/api/share/verify` | 校验提取码 |
| GET | `/api/share/list` | 分享文件夹列表 |
| GET | `/api/share/download` | 分享文件下载 |
| POST | `/api/transfer/upload` | 中转站上传（multipart `file` 字段）|
| GET | `/api/transfer/info?code=` | 查询中转文件信息 |
| POST | `/api/transfer/verify` | 校验提取码 |
| GET | `/api/transfer/download?code=&pin=` | 中转文件下载 |
| GET | `/api/transfer/mine` | 我的中转记录 |
| POST | `/api/transfer/delete` | 删除中转记录 |

**需登录接口**（`Authorization: Bearer <token>`）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/list?path=` | 目录列表 |
| POST | `/api/upload?path=` | 上传（multipart `file` 字段）|
| GET | `/api/download?path=` | 下载 |
| POST | `/api/mkdir` | 新建文件夹 `{"path":"..."}` |
| POST | `/api/delete` | 删除 `{"path":"...","is_dir":bool}` |
| POST | `/api/share/create` | 创建分享 |
| GET | `/api/shares` | 列出所有分享 |
| POST | `/api/share/delete` | 删除分享 |
| GET | `/api/tg/status` | Telegram 连接状态 |
| GET | `/api/tg/config` | 获取 Telegram 配置 |
| POST | `/api/tg/config` | 保存 Telegram 配置 |
| POST | `/api/tg/connect` | 连接测试 |
| POST | `/api/tg/test-proxy` | 测试 mihomo 本地 SOCKS5 代理可用性 |
| POST | `/api/tg/fetch-proxy` | 兼容保留接口（当前不再自动获取香港代理） |
| POST | `/api/offline/create` | 创建离线任务 `{"urls":[],"store":"","path":""}` |
| GET | `/api/offline/list` | 列出离线任务 |
| POST | `/api/offline/retry` | 重试失败任务 `{"id":1}` |
| POST | `/api/offline/delete` | 删除任务记录 `{"id":1}` |
| POST | `/api/logout` | 退出登录 |

## 分享机制

- 分享码：8 位 base62（排除易混淆字符）
- 提取码：4 位数字，仅存 SHA-256 哈希，不存明文
- 文件夹分享：可浏览子目录，逐文件下载；路径经过越权检查，无法逃出分享根目录
- 有效期：过期后自动失效

## Telegram 存储与中转站

### 准备工作

1. **创建 Bot**：在 Telegram 中与 [@BotFather](https://t.me/BotFather) 对话，发送 `/newbot` 创建机器人，获取 `bot_token`。
2. **获取聊天 ID**：将机器人拉入目标频道/群组，或与 [@userinfobot](https://t.me/userinfobot) 对话获取聊天 ID（形如 `-1001234567890`）。
3. **API ID / Hash**：已内置默认值，无需配置。如需自定义可在 `tg.api_id` / `tg.api_hash` 中填写。

### 配置

在 `config.yaml` 中填写 `tg` 段：

```yaml
tg:
  bot_token: "123456:ABC-DEF..."
  chat_id: "-1001234567890"
  # api_id / api_hash 可省略，使用内置默认值
  # 代理由 Docker 内 mihomo 解析 Clash 订阅并提供本地 SOCKS5，不再由网盘程序自动获取香港代理
```

> 国内网络访问 Telegram 通常需要 SOCKS5 代理。Docker 部署时，mihomo 负责拉取并解析 Clash 订阅，在 `127.0.0.1:7891` 提供 SOCKS5；网盘程序只连接该本地代理，S3/WebDAV 默认直连。

### 使用

- 在网盘主界面点击「Telegram 设置」可查看连接状态、修改配置、测试代理。
- 点击「中转站」进入文件中转站，上传文件后获得分享码与提取码，7 天内可提取下载；复制链接可自动携带提取码。
- 中转站上传后会显示实时进度；上传完成后 Telegram 仍可能需要一段处理时间，界面会显示“处理中”。
- Telegram 单文件上限默认约 2GB，当前不做大文件分片上传或下载合并；可在网盘「Telegram 设置」中调整上限，但最大仍为 2GB。
- 浏览器上传、下载都经过网盘服务转发：上传时网盘将数据流写入存储，Telegram 下载采用流式转发，不会在服务器磁盘保存完整文件。
- 下载中断不会删除 Telegram 中的文件；中转记录会保留到过期清理。

## 离线资源采集

离线采集允许你把下载链接交给服务器，由服务器在后台自动完成「下载 → 上传到指定存储空间」，适合让服务器当下载机把资源拉回网盘。

### 使用

1. 在网盘主界面点击「离线采集」进入。
2. 在「下载链接」中粘贴一个或多个 URL（每行一个）。
3. 选择目标**存储空间**，并填写**存储路径**（目录，根目录可填 `/`；目录不存在会自动创建，文件名取自下载内容）。
4. 点击「开始采集」。多个任务会**顺序执行**，排队中/下载中/上传中的任务会实时显示进度。

### 说明

- 任务是后台执行的，**关闭网页甚至浏览器后服务器仍会继续**，稍后可回到页面查看执行情况。
- 下载会先落到服务器数据目录的临时文件（`offline_tmp/`），上传完成后**自动删除本地临时文件**，不长期占用服务器磁盘。
- 支持状态：排队中 → 下载中 → 上传中 → 已完成 / 失败；失败任务可点击「重试」重新排队。
- 下载会遵循 HTTP 重定向，并从 `Content-Disposition` 或 URL 推断文件名；对超大文件没有额外限制，取决于磁盘空间与网络。
- 数据记录保存在 SQLite（`offline.db`），进程重启后历史任务依然存在。

## 常见问题

### 获取 S3 凭证（CSTCloud 数据胶囊为例）

进入数据胶囊 → 你的数据空间 → **客户端访问** → **S3 客户端** → **新增 AccessKey**，把得到的 AccessKey ID 和 Secret AccessKey 填到 `config.yaml` 的 `s3.access_key` 和 `s3.secret_key`。**桶名**（bucket）即数据空间名。

数据胶囊等部分 S3 服务只支持 **Path-Style** URL，本项目默认使用，无须额外配置。

## 安全说明

- 登录密码与 S3 AccessKey 务必使用强密码/高熵密钥，且与默认值不同
- 建议部署在 HTTPS 反向代理（如 Caddy/Nginx）之后，避免明文传输
- 会话为内存态，服务重启后需重新登录