mirror of
https://github.com/saltbo/zpan.git
synced 2026-08-28 15:51:29 +08:00
saltbo
177 lines
16 KiB
Markdown
177 lines
16 KiB
Markdown
<p align="center">
|
||
<img src="../../public/logo.png" alt="ZPan logo" width="128" height="128" />
|
||
</p>
|
||
|
||
<h1 align="center">ZPan</h1>
|
||
|
||
<p align="center">
|
||
<strong>Файловый хостинг с открытым исходным кодом для вашего S3-совместимого хранилища.</strong>
|
||
</p>
|
||
|
||
<p align="center">
|
||
Разворачивайте на Cloudflare Workers или в Docker. Загружайте файлы напрямую в объектное хранилище.
|
||
</p>
|
||
|
||
<p align="center">
|
||
<a href="https://github.com/saltbo/zpan/actions/workflows/ci.yml"><img src="https://github.com/saltbo/zpan/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
|
||
<a href="https://codecov.io/gh/saltbo/zpan"><img src="https://codecov.io/gh/saltbo/zpan/graph/badge.svg" alt="codecov" /></a>
|
||
<a href="https://github.com/saltbo/zpan/actions/workflows/release.yml"><img src="https://github.com/saltbo/zpan/actions/workflows/release.yml/badge.svg" alt="Release" /></a>
|
||
<a href="https://github.com/saltbo/zpan/releases/latest"><img src="https://img.shields.io/github/v/release/saltbo/zpan" alt="GitHub Release" /></a>
|
||
<a href="https://ghcr.io/saltbo/zpan"><img src="https://img.shields.io/badge/ghcr.io-saltbo%2Fzpan-blue" alt="Docker Image" /></a>
|
||
<a href="https://github.com/saltbo/zpan/blob/main/LICENSE"><img src="https://img.shields.io/github/license/saltbo/zpan.svg" alt="License" /></a>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<a href="../../README.md">English</a> ·
|
||
<a href="README.zh-CN.md">简体中文</a> ·
|
||
<a href="README.ja.md">日本語</a> ·
|
||
<a href="README.ko.md">한국어</a> ·
|
||
<strong>Русский</strong> ·
|
||
<a href="README.es.md">Español</a> ·
|
||
<a href="README.pt-BR.md">Português (BR)</a>
|
||
</p>
|
||
|
||
## Что такое ZPan?
|
||
|
||
ZPan — это лёгкая платформа файлового хостинга, построенная поверх S3-совместимого хранилища. Файлы загружаются напрямую с клиента в S3 через предподписанные (presigned) URL, полностью минуя пропускную способность сервера. Сервер выступает как уровень управления: аутентификация, метаданные, общий доступ, квоты, команды, WebDAV, интеграции с инструментами и административные операции.
|
||
|
||
Границы продукта намеренно очерчены: ZPan — это специализированный веб-диск на базе S3, а не обёртка над всеми потребительскими облачными дисками и не полноценный набор групповых приложений. Вы предоставляете S3-совместимый бакет, а ZPan даёт ему чистый веб-интерфейс, публичный общий доступ, API для хостинга изображений и варианты развёртывания, которые не требуют VPS или NAS.
|
||
|
||
**Основные сценарии:**
|
||
|
||
- **Веб-диск на S3** — управляйте файлами, папками, предпросмотрами, корзиной, квотами и командными рабочими пространствами поверх собственного объектного хранилища
|
||
- **Хостинг изображений** — загружайте через PicGo, PicList, uPic, ShareX, Flameshot или API и мгновенно получайте стабильный URL
|
||
- **Общий доступ к файлам** — публикуйте ссылки с паролем, сроком действия, лимитом загрузок, прямыми ссылками и возможностью сохранения на диск
|
||
- **Персональная домашняя страница** — дайте каждому пользователю публичную страницу `/u/username` с подобранными общими файлами и просмотром в стиле папок
|
||
- **Внешний доступ** — монтируйте файлы через WebDAV и запускайте воркеры-загрузчики для удалённой загрузки
|
||
|
||
## Почему ZPan?
|
||
|
||
**Только S3, по замыслу.** ZPan не гонится за каждым облачным диском и не строит слой вложенных облачных хранилищ. Контракт хранилища остаётся простым и надёжным: S3-совместимые бакеты, такие как Cloudflare R2, AWS S3, Backblaze B2, MinIO, RustFS, Tigris и другие S3-совместимые сервисы.
|
||
|
||
**Cloudflare Workers в первую очередь.** ZPan построен вокруг Cloudflare Workers, D1, Hono и веб-стандартных API, а Docker и другие среды выполнения служат дополнительными целями развёртывания. Вы можете запустить полноценный уровень управления файловым хостингом, не владея VPS, не держа NAS включённым и не проксируя загрузки через постоянно работающий сервер.
|
||
|
||
**Прямой путь передачи.** Загрузки и скачивания используют предподписанные URL объектного хранилища, когда это возможно. Это снижает нагрузку на пропускную способность сервера, устраняет центральное узкое место передачи файлов и позволяет объектному хранилищу выполнять основную работу.
|
||
|
||
**Практичные сценарии работы с файлами.** ZPan включает веб-файловый менеджер, публичный общий доступ, настройку хостинга изображений, API-ключи, доступ по WebDAV, команды, квоты, задачи удалённой загрузки, предпросмотр файлов и административные элементы управления — не превращаясь при этом в платформу-агрегатор провайдеров.
|
||
|
||
**Разворачиваемые воркеры-загрузчики.** Удалённая загрузка не обязана выполняться внутри основного экземпляра ZPan. Вы можете развернуть загрузчик вместе с ZPan для простой настройки или запустить его отдельно в окружении с лучшим сетевым доступом и меньшими ограничениями со стороны исходных сайтов, а затем позволить ZPan импортировать завершённые файлы в объектное хранилище.
|
||
|
||
## Границы продукта
|
||
|
||
ZPan хорошо подходит, когда вам нужно:
|
||
|
||
- Сфокусированный веб-диск на базе S3 вместо зоопарка провайдеров хранилищ
|
||
- Самостоятельно размещаемый хостинг изображений и приложение для обмена файлами на базе собственного бакета
|
||
- Развёртывание в экосистеме Cloudflare без обслуживания VPS или NAS
|
||
- Передача из браузера в S3 вместо проксирования файлов через сервер приложения
|
||
- Интеграции с инструментами для скриншотов, публикации, WebDAV, удалённой загрузки и сценариев на основе API
|
||
|
||
ZPan не стремится быть:
|
||
|
||
- Набором для совместного редактирования документов в реальном времени, как Nextcloud Office
|
||
- Универсальным агрегатором облачных дисков, как AList
|
||
- Браузером локальных серверных каталогов, как File Browser
|
||
|
||
## Как ZPan соотносится с другими
|
||
|
||
Большинство проектов самостоятельного файлового хостинга отталкиваются либо от серверных файлов, либо от синхронизации с настольным ПК, либо от совместной работы, либо от агрегации множества провайдеров. ZPan отталкивается от S3-совместимого объектного хранилища и уровня управления, дружественного к Cloudflare Workers.
|
||
|
||
| Возможность | **ZPan** | [Cloudreve](https://docs.cloudreve.org/en/) | [AList](https://alist-repo.github.io/docs/guide/drivers/) | [Nextcloud](https://nextcloud.com/files/) | [Seafile](https://www.seafile.com/en/features/) | [File Browser](https://github.com/filebrowser/filebrowser) |
|
||
|------------|----------|------------|--------|-----------|---------|--------------|
|
||
| Ориентация на продукт на базе S3 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||
| S3-совместимый бэкенд хранилища | ✅ | ✅ | ✅ | ✅ | ⚠️ | ❌ |
|
||
| Прямой путь из браузера в объектное хранилище | ✅ | ⚠️ | ⚠️ | ❌ | ❌ | ❌ |
|
||
| Развёртывание на Cloudflare Workers | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||
| Не требуется VPS/NAS | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||
| Сценарий хостинга изображений PicGo/ShareX | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||
| Публичная домашняя страница файлов для каждого пользователя | ✅ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ❌ |
|
||
| Сценарий удалённой загрузки | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
|
||
| Отдельно разворачиваемый загрузчик/узел | ✅ | ✅ | ⚠️ | ❌ | ❌ | ❌ |
|
||
| Агрегация нескольких облачных дисков | ❌ | ❌ | ✅ | ⚠️ | ❌ | ❌ |
|
||
| Локальный серверный каталог как основной корень файлов | ❌ | ⚠️ | ⚠️ | ⚠️ | ❌ | ✅ |
|
||
| Совместное редактирование документов в реальном времени | ❌ | ❌ | ❌ | ✅ | ⚠️ | ❌ |
|
||
| Выделенные клиенты синхронизации | Запланировано | ❌ | ❌ | ✅ | ✅ | ❌ |
|
||
| Модель команд/рабочих пространств | ✅ | ⚠️ | ❌ | ✅ | ✅ | ❌ |
|
||
| Доступ по WebDAV | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
|
||
| Ссылки для общего доступа | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||
| Развёртывание в Docker | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||
|
||
Условные обозначения: ✅ первоклассная или ключевая возможность; ⚠️ частичная, зависящая от редакции или не являющаяся основным фокусом продукта; ❌ не является ключевой возможностью.
|
||
|
||
## Развёртывание
|
||
|
||
### Cloudflare Workers (рекомендуется)
|
||
|
||
Разворачивайте через GitHub Actions без управления сервером. Бесплатного тарифа достаточно для личного использования.
|
||
|
||
1. **Сделайте форк** этого репозитория
|
||
2. В своём форке перейдите в **Settings → Secrets and variables → Actions** и добавьте:
|
||
- `CLOUDFLARE_ACCOUNT_ID` — находится в боковой панели [панели управления Cloudflare](https://dash.cloudflare.com/)
|
||
- `CLOUDFLARE_API_TOKEN` — создайте его [здесь](https://dash.cloudflare.com/profile/api-tokens) с правами **Workers Scripts:Edit**, **D1:Edit** и **R2 Storage:Edit** (область R2 нужна для автоматического создания бакета для аватаров/логотипа)
|
||
3. Перейдите на вкладку **Actions**, выберите **Deploy to Cloudflare Workers** и нажмите **Run workflow**
|
||
|
||
После первоначальной настройки workflow запускается автоматически каждый раз, когда вы синхронизируете свой форк с последним релизом.
|
||
|
||
### AWS Lambda
|
||
|
||
Разворачивайте через GitHub Actions с использованием SAM. Lambda Function URL обеспечивает HTTPS без необходимости в API Gateway.
|
||
|
||
1. **Сделайте форк** этого репозитория
|
||
2. В своём форке перейдите в **Settings → Secrets and variables → Actions** и добавьте:
|
||
- `TURSO_DATABASE_URL` и `TURSO_AUTH_TOKEN` — из [Turso](https://turso.tech) (бесплатно, без банковской карты)
|
||
- `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`
|
||
3. Перейдите на вкладку **Actions**, выберите **Deploy to AWS Lambda** и нажмите **Run workflow**
|
||
|
||
См. [docs/deploy/aws-lambda.md](../deploy/aws-lambda.md) для полных инструкций по настройке и прав IAM.
|
||
|
||
### Docker
|
||
|
||
**Быстрый старт** — загрузите готовый образ и подключите своё S3-хранилище:
|
||
|
||
```bash
|
||
curl -O https://raw.githubusercontent.com/saltbo/zpan/main/deploy/docker-compose.yml
|
||
docker compose up -d
|
||
```
|
||
|
||
**С RustFS** (самостоятельно размещаемое S3-совместимое хранилище, без внешних зависимостей):
|
||
|
||
```bash
|
||
curl -O https://raw.githubusercontent.com/saltbo/zpan/main/deploy/docker-compose.rustfs.yml
|
||
docker compose -f docker-compose.rustfs.yml up -d
|
||
```
|
||
|
||
После запуска:
|
||
|
||
1. Откройте консоль RustFS по адресу `http://localhost:9001` (admin / admin123) и создайте бакет (например, `zpan-bucket`)
|
||
2. Откройте ZPan по адресу `http://localhost:8222`, зарегистрируйте пользователя (первый пользователь получает роль администратора)
|
||
3. Перейдите в **Admin → Storage** и добавьте хранилище RustFS:
|
||
- **Endpoint**: `http://localhost:9000` (должен быть доступен из вашего браузера, а не внутренний хостнейм Docker)
|
||
- **Bucket**: имя бакета, который вы создали на шаге 1
|
||
- **Region**: `us-east-1`
|
||
- **Access Key / Secret Key**: `admin` / `admin123`
|
||
|
||
> **Важно:** конечная точка хранилища должна быть доступна из **браузера клиента**, поскольку файлы загружаются напрямую в S3 через предподписанные URL. Используйте `http://localhost:9000` для локальной разработки или публичный URL вашего сервера для продакшена.
|
||
|
||
## Документация
|
||
|
||
- [Дорожная карта](../../V2_ROADMAP.md)
|
||
- [Участие в разработке](../../CONTRIBUTING.md)
|
||
|
||
## v1
|
||
|
||
Ищете ZPan v1 (версия на Go)? См. [ветку v1](https://github.com/saltbo/zpan/tree/v1).
|
||
|
||
## Участие в разработке
|
||
|
||
Подробности см. в [CONTRIBUTING.md](../../CONTRIBUTING.md).
|
||
|
||
Спасибо всем, кто внёс свой вклад в ZPan!
|
||
|
||
<a href="https://github.com/saltbo/zpan/graphs/contributors"><img src="https://opencollective.com/zpan/contributors.svg?width=890" /></a>
|
||
|
||
## Лицензия
|
||
|
||
ZPan распространяется под лицензией GNU Affero General Public License v3.0. Подробности см. в файле
|
||
[LICENSE](../../LICENSE).
|