主题

快速开始 ​

欢迎来到 AsterDrive 🌟

这是一个自托管的云存储——你把它装在自己的服务器上，文件就真的是你的，不在任何第三方手里。

适合三类人：

  • 想替代商业网盘，但又不想自己拼一堆开源组件的人
  • 想给家人共享照片视频、希望爸妈也能用得明白的人
  • 小团队需要一个轻、快、改得动的方案

如果你是第一次接触自托管，AsterDrive 默认配置就能跑起来——10 分钟内可以看到自己的第一个文件躺在自己服务器上的感觉。我们试过让这件事尽量不需要你先成为运维专家。

如果你已经熟悉 Docker、反向代理这些，可以直接跳到 部署手册。

AsterDrive 不会有付费版、Pro 版或功能墙——所有功能在 MIT 协议下开源，每个人能用到的东西完全一样。关于这个项目的取舍和后续路线，可以看 关于 AsterDrive。

来吧，开始。

1. 先把服务启动起来 ​

最简单的方式是直接运行官方 Docker 镜像。镜像内以非 root 用户 aster（UID/GID 10001:10001）运行，因此需要先在宿主机准备好目录、对齐属主，再交由容器挂载：

bash
mkdir -p ./data
sudo chown -R 10001:10001 ./data

docker run -d \
  --name asterdrive \
  -p 3000:3000 \
  -e ASTER__SERVER__HOST=0.0.0.0 \
  -e ASTER__AUTH__BOOTSTRAP_INSECURE_COOKIES=true \
  -e ASTER__DATABASE__URL="sqlite:///data/asterdrive.db?mode=rwc" \
  -v "$(pwd)/data:/data" \
  ghcr.io/apts-1547/asterdrive:latest

这条命令适合本机、内网或临时纯 HTTP 试跑环境。

  • 如果你已经准备好通过 HTTPS 对外访问，可以去掉 ASTER__AUTH__BOOTSTRAP_INSECURE_COOKIES=true
  • 正式上线时，建议保持 bootstrap_insecure_cookies = false，并让后台系统设置里的 Cookie 安全开关保持开启

为什么必须 chown 给 10001

镜像内部由 UID 10001 的 aster 用户负责写入 /data。如果直接将一个属主为当前 shell 用户的目录 bind mount 进去，容器启动时将无法写入 config.toml、SQLite 文件和临时目录，会因权限错误直接退出。

更详细的写法和 Compose 示例参见 Docker 部署。

为什么默认是 SQLite 不是 PostgreSQL？

SQLite 的好处是：零运维、单文件备份（直接复制走）、试用门槛低到几乎为零。

我们的判断是：让你用 5 分钟看一下"这个项目是什么" 比 强迫你先装一个数据库 更重要。

真要上线、或者数据规模大了，再切到 PostgreSQL——AsterDrive 自带 跨数据库迁移工具，迁移命令直接迁，不会被困死在 SQLite 里。

首次成功启动后，AsterDrive 会自动完成下面这些准备：

  • 在当前工作目录的 data/ 下生成 config.toml
  • 创建或连接数据库，并自动更新数据库结构
  • 创建默认本地存储策略 Local Default
  • 创建默认策略组 Default Policy Group
  • 创建本地上传目录 data/uploads
  • 创建临时目录 data/.tmp 和 data/.uploads
  • 初始化后台默认设置，并启动必要的后台任务

如果你使用官方 Docker 镜像并按上面的命令挂载 ./data:/data：

  • 数据库和上传目录会落到容器里的 /data，对应宿主机的 ./data/
  • config.toml 会生成在容器里的 /data/config.toml，对应宿主机的 ./data/config.toml，可以直接在宿主机上编辑

打开地址：

text
http://服务器地址:3000

2. 创建第一个管理员账号 ​

浏览器打开站点后，登录页会根据你输入的用户名或邮箱自动判断流程：

  • 系统里还没有任何用户：创建管理员账号
  • 输入的是已有账号：登录
  • 输入的是新账号，而且管理员允许公开注册：注册普通账号

第一个创建成功的账号会自动成为管理员。

第一个管理员账号是直接创建并立即可用的。
后续普通用户如果通过公开注册创建账号，需要先完成邮箱激活。

如果你准备直接对公网开放服务，至少先确认下面两件事：

  1. 公开注册是否真的要开启
  2. 邮件投递和公开站点地址是否已经配置好

3. 先做一轮最基础的可用性检查 ​

管理员登录后，先在"我的空间"里完成这几步：

  1. 新建一个测试文件夹
  2. 上传一个小文件
  3. 打开文件，确认可以预览、编辑或下载
  4. 把文件删除到回收站
  5. 再从回收站恢复回来

这几步都能正常完成，说明浏览器端、数据库和默认存储路线已经基本可用。

我们认为回收站是 AsterDrive 最重要的功能之一——没有它，你不敢真的把重要文件放进去。所以第一次跑通时就该亲手验证一次"误删能找回"。

4. 试一次分享 ​

在文件或文件夹的操作菜单里创建分享链接，并按需要设置：

  • 密码
  • 过期时间
  • 最大下载次数

把链接发到无痕窗口、手机或另一台设备里，确认公开页面能正常打开。

5. 如果要用 WebDAV，再做一次真实连接 ​

如果你准备让 Finder、Windows 资源管理器、rclone 或同步工具接入：

  1. 先切回 我的空间，再打开左侧 WebDAV
  2. 创建一个专用 WebDAV 账号
  3. 复制 WebDAV 地址、用户名和密码
  4. 在客户端里做一次读写测试

密码只会在创建成功时显示一次，建议立刻保存到密码管理器。

6. 管理员第一次登录后至少检查这些地方 ​

  • 管理 -> 概览
  • 管理 -> 用户
  • 管理 -> 团队
  • 管理 -> 存储策略
  • 管理 -> 策略组
  • 管理 -> 任务
  • 管理 -> 系统设置
  • 回到个人空间后，左侧 WebDAV

如果你准备接从节点，再补看 管理 -> 远程节点。

重点确认：

  • 默认存储策略和默认策略组已经创建
  • 新用户默认配额是否合适；如果你会创建团队，创建后再确认实际团队配额和默认策略组
  • 如果站点准备对外访问，公开站点地址 是否已经填成真实 HTTP(S) 来源；多个公开入口逐项添加
  • 如果要开放注册、找回密码或邮箱改绑，测试邮件是否已经发通
  • 如果要接 OnlyOffice 一类 WOPI 服务，公开站点地址 和 站点配置 -> 预览应用 是否已经配好，外部服务是否能回连 AsterDrive 的 /api/v1/wopi/...
  • 如果会用在线压缩、在线解压或其他后台任务，管理 -> 任务 里最近有没有持续失败记录
  • 如果会用图片 / 视频缩略图，存储与保留 -> 媒体处理 里的处理器是否符合当前服务器环境
  • 回收站保留天数、历史版本数量和团队归档保留天数是否符合预期
  • WebDAV 是否需要保持开启
  • 文件是否继续落本地，还是要改到 S3 / MinIO / 远程节点；如果用远程节点，follower 是否已经有默认接收落点
  • Gravatar 头像地址在当前网络里是否可访问

7. 正式上线前做一轮验收 ​

完整验收清单见 首次启动检查。

快速开始最少跑通这几项就可以：

  • 浏览器可以正常登录和退出
  • 文件可以上传、下载、删除到回收站并恢复
  • 分享链接可以正常打开
  • http://服务器地址:3000/health 和 /health/ready 返回正常

通过这轮检查后，再继续做域名、HTTPS、反向代理、备份和升级安排。

如果你还想在命令行里再做一轮离线检查，可以继续跑一遍 运维 CLI 里的 doctor。

然后呢 ​

跑通之后，下面这些可能是你接下来想做的：

或者，如果你想先了解这个项目本身：关于 AsterDrive。

别给自己的数据增加心智负担——这是我们做 AsterDrive 的初衷。
祝你用得开心。

基于 MIT 许可证发布

Copyright © 2026 AptS:1547