本文作者:icy

otter-webdav,家里 / 办公室一台机器上的目录,想让手机、平板、其它电脑都能像本地磁盘一样读写的文档共享服务

icy 昨天 29 抢沙发
otter-webdav,家里 / 办公室一台机器上的目录,想让手机、平板、其它电脑都能像本地磁盘一样读写的文档共享服务摘要: otter-webdav把本机目录变成一个可通过 WebDAV 访问的文档共享服务。单个可执行文件,内置 ,管理台、多账号隔离、多挂载点、浏览器目录页,以及 frpc 反向代理接入...

otter-webdav,家里 / 办公室一台机器上的目录,想让手机、平板、其它电脑都能像本地磁盘一样读写的文档共享服务

otter-webdav,家里 / 办公室一台机器上的目录,想让手机、平板、其它电脑都能像本地磁盘一样读写的文档共享服务

otter-webdav


把本机目录变成一个可通过 WebDAV 访问的文档共享服务。单个可执行文件,内置 ,管理台、多账号隔离、多挂载点、浏览器目录页,以及 frpc 反向代理接入。

  • 当前版本:0.1.0

  • 进程名 / 管理接口名:otter-webdav

  • 默认管理台:http://127.0.0.1:18761/

  • 默认共享端口:8081

项目简介

otter-webdav 面向「家里 / 办公室一台机器上的目录,想让手机、平板、其它电脑 都能像本地磁盘一样读写」的场景:

  • 服务端只跑一个二进制,不依赖数据库、反向代理或额外运行时;

  • 每个账号拥有独立的私有目录,也可以配置所有人共享的公共目录;

  • 不装客户端时,浏览器打开共享地址即可浏览、上传、下载、重命名、删除;

  • 需要远程访问时,可在配置中内嵌 frpc,把本地共享端口注册到公网 frps。

核心特性

能力说明
WebDAV 协议支持 OPTIONS / GET / HEAD / PUT / DELETE / MKCOL / COPY / MOVE / PROPFIND / PROPPATCH / LOCK / UNLOCK,Basic 认证
多挂载点一个共享根下挂载任意多个虚拟目录,每个挂载点可独立配置真实路径与只读
账号隔离perUser 挂载点按 账号名 自动隔离为 <path>/<用户名>,账号之间互不可见
三级只读全局只读(share.readonly)→ 挂载点只读(mounts[].readonly)→ 账号权限(permission)
浏览器目录页列表 / 网格视图、缩略图、图片与视频预览、拖拽上传、新建文件夹、重命名、删除、按名称筛选
可视化管理台登录、共享启停 / 重启、共享配置、账号增删改、启停、重置密码、修改管理员密码、界面皮肤
配置持久化管理台的所有修改都会原子写回 config.cfg(0600),并保持「配置内容 == 实际运行状态」
子路径前缀支持挂载在反向代理的子路径下(如 /otter),带前缀与不带前缀的请求都可用
frpc 内嵌配置 frpc 段后自动把共享端口注册到 frps,断线自动重连
单实例保护通过系统临时目录下的文件锁避免重复启动撞端口
优雅退出收到 Ctrl+C / SIGTERM 后先停共享、再停管理接口(5 秒超时)

快速开始

环境要求

  • Windows、Linux 均可运行;


启动后控制台会打印管理台地址,例如:

otter-webdav 已启动 配置=...\bin\config.cfg
后台管理信息 地址=http://127.0.0.1:18761/ 管理员=admin
管理接口已监听 addr=127.0.0.1:18761
文档共享已监听 addr=[::]:8081 prefix= readonly=false

浏览器打开 http://127.0.0.1:18761/ 登录管理台,即可启停共享、配置挂载点、管理账号。

首次启动与默认密码

  1. 配置文件不存在时自动生成默认配置:管理员账号 admin、密码为空, 启动时随机生成 16 位密码并只在控制台输出一次;共享默认不自动开启 (share.enabled = false),默认挂载点为 share/<用户名>(perUser = true)。

  2. 仓库自带的示例 bin/config.cfg:管理员为 admin,密码为 qwertyuiop(配置中保存的是其 SHA256 哈希)。正式使用前请登录管理台,在「设置 → 管理员密码」 中修改。

  3. 管理台会话只保存在内存,进程重启后需要重新登录;配置文件以 0600 权限原子写盘, 只有密码哈希,不保存管理台明文密码。

配置文件

位置与查找顺序

程序按以下优先级确定配置文件:

  1. 命令行参数 -config <路径>;

  2. 环境变量 OTTER_CONFIG;

  3. 可执行文件同目录下的 config.cfg(存在时);

  4. 当前工作目录下的 config.cfg(存在时);

  5. 可执行文件同目录下的 config.cfg(不存在则创建)。

share.dir 与 mounts[].path 使用相对路径时,按配置文件所在目录解析。

完整示例

{
  admin = {
    host = 127.0.0.1,
    port = 18761,
    user = admin,
    password = 'change-me-please',
    sessionHours = 12
  },
  share = {
    dir = share,
    port = 8081,
    enabled = true,
    readonly = false,
    prefix = '',
    mounts = {
      { name = 我的文件, path = share/users, perUser = true, readonly = false },
      { name = 公共资料, path = share/public, perUser = false, readonly = false },
      { name = 视频, path = media/videos, perUser = false, readonly = true }
    }
  },
  frpc = {
    enable = false,
    serverAddr = frps.example.com,
    serverPort = 7000,
    token = 'your-frps-token',
    proxies = {
      { name = otter-http, type = http, localIP = 127.0.0.1, localPort = 8081, domain = dav.example.com, location = /otter, locations = {} }
    }
  },
  webPrefix = ''
}
  • 整个配置是一个表,必须用外层 { ... } 包裹;表内省略外层括号会导致解析失败。

  • 字符串一般可直接书写;含空格或特殊字符时用单引号包裹。

  • mounts[].path 可以写绝对路径或相对路径,相对路径按配置文件所在目录解析; Windows 上的绝对路径需要带盘符(如 D:/videos),/data/videos 这类写法在 Windows 上会被当作相对路径,Linux / macOS 上才是绝对路径。

  • users 段由管理台自动维护,手写时 password 必须是 SHA256 哈希(见下文)。

  • 配置由程序规范化后原子写回:旧版的 share.privateName / share.publicName会自动迁移为 share.mounts,新配置中不再出现这两个字段。

admin 段

键类型默认值说明
hoststring127.0.0.1管理接口监听地址,默认只允许本机访问
portint18761管理接口端口
userstringadmin管理员账号
passwordstring空SHA256 哈希;也可直接写明文,启动时自动转换并写回。为空时启动随机生成 16 位密码并只打印一次
sessionHoursint12登录会话有效期(小时),上限 30 天

share 段

键类型默认值说明
dirstringshare默认共享根目录,仅在未配置挂载点时用于生成默认私有挂载点
portint8081WebDAV 监听端口(共享端口)
enabledbool新配置为 false进程启动时是否自动开启共享
readonlyboolfalse全局只读,所有账号、所有挂载点都不可写
prefixstring空反向代理子路径前缀,如 /otter;空表示根路径
mounts[].namestring我的文件WebDAV 顶层虚拟目录名,必须唯一
mounts[].pathstringshare真实目录;相对路径按配置文件目录解析
mounts[].perUserbool默认挂载点为 truetrue 时映射到 <path>/<用户名>;false 时所有账号共享 <path>
mounts[].readonlyboolfalse该挂载点对所有人只读(即使账号有写权限)

挂载点与路径语义:

  • 虚拟根 / 只列出配置的挂载点,不允许写入、删除、重命名或移动;

  • /<挂载点>/... 映射到真实目录,未知的顶层名称一律视为不存在(404);

  • 不允许跨挂载点 MOVE / COPY,避免在不同账号目录之间搬运文件;

  • 挂载点名称不能为空、不能是 . / ..、不能包含 / 或 \,且不能重复;

  • 至少保留一个挂载点;启动时会自动创建缺失的挂载点目录。

只读判定从严格到宽松依次是:

  1. share.readonly = true:全局只读,任何人不可写;

  2. mounts[].readonly = true:该挂载点不可写;

  3. 账号 permission = 0 或 enabled = false:该账号不可写 / 无法认证;

  4. 其余情况可写(permission = 1 且账号已启用)。

users 段

通常由管理台维护,无需手工编辑。字段与账号模型一致:

键类型说明
idint账号 ID,自动分配
usernamestring登录名,同时作为私有目录名。不能为空、不超过 64 字节、不能是 . / ..、不能以 . 开头、不能包含 / \ : 或控制字符
passwordstringSHA256 十六进制哈希(64 字符)。手写明文不会被自动转换,请通过管理台创建账号或重置密码
nicknamestring昵称,仅用于展示
descriptionstring备注
permissionint0 只读,1 可读写(其他值按可读写处理)
enabledbool是否启用;停用后立即无法通过 WebDAV 认证
createdAtint创建时间(Unix 秒),为 0 时自动补当前时间

删除账号不会删除其私有目录中的文件,只是立即收回访问权限;需要清理数据时请手动处理。

frpc 段

键类型默认值说明
enableboolfalse是否在共享启动后接入 frps
serverAddrstring空frps 地址;为空则跳过接入
serverPortint7000frps 服务端口
tokenstring空frps 认证令牌
proxies[].namestring必填代理名称,需在 frps 侧唯一
proxies[].typestringhttphttp 或 tcp
proxies[].localIPstring127.0.0.1本地服务地址
proxies[].localPortint必填本地端口,通常等于 share.port
proxies[].remotePortint0tcp 类型映射到 frps 的端口
proxies[].domainstring空http 类型按 Host 路由的域名
proxies[].subDomainstring空或使用 frps 的 subdomain_host
proxies[].locationstring空http 类型的单个路径前缀(如 /otter)
proxies[].locations[]string空http 类型的多个路径前缀;为空时使用 location

frpc 行为:

  • 只有在共享启动成功后才接入(enable = true、serverAddr 非空、至少一个代理);

  • 连接失败不影响本地使用,控制台会给出提示,frp 客户端会在后台自动重连;

  • 停止共享不会主动断开 frpc,进程退出时结束接入;

  • 若 share.prefix 为空,程序会从 localPort == share.port 的 http 代理的location / locations 推导共享前缀(都没有时再回退到顶层 webPrefix), 远端挂在 /otter 下时无需重复配置。

运行时行为

  • 自动开启:share.enabled = true 时,进程启动后自动启动共享;启动失败 (端口占用、目录不可写等)只记录日志,进程继续运行,管理台仍可修正配置后重试;

  • 启停会写配置:管理台「启动共享」会把 enabled 置为 true,「停止共享」置为false,因此停止后重启进程不会自动开启;

  • 热切换:运行中可即时修改 prefix 与 readonly;修改 port 或 mounts需要先停止共享,否则接口返回 409 Conflict;

  • 账号变更即时生效:新增、改密、停用、删除账号都无需重启共享;

  • 单实例:锁文件位于系统临时目录(如 %TEMP%\otter-webdav.lock、/tmp/otter-webdav.lock),重复启动会直接报错退出;

  • 优雅退出:Ctrl+C 或 SIGTERM 后先停共享再停管理接口,超时 5 秒。

管理台使用

浏览器打开 http://<admin.host>:<admin.port>/(默认 http://127.0.0.1:18761/)。

登录与会话

  • 账号为 admin.user(默认 admin),密码为 admin.password 对应的明文; 忘记密码时见「常见问题」;

  • 登录成功后服务端下发 HttpOnly + SameSite=Strict 的会话 Cookie,会话仅保存在内存, 进程重启后需重新登录;有效期由 admin.sessionHours 控制(默认 12 小时);

  • 登录失败统一提示「账号或密码不正确」,不区分账号不存在与密码错误;

  • 管理接口只服务同源页面,不开放 CORS,并带有 CSP / X-Frame-Options 等安全响应头。

共享状态

  • 展示运行状态、访问地址(本机局域网 IPv4 + 访问前缀,可一键复制)、挂载点列表、 访问前缀、监听端口、读写策略、账号数量、启动时间、管理接口地址与配置文件路径;

  • 提供「启动共享 / 停止 / 重启」操作;停止后所有客户端连接会断开;

  • 页面每 5 秒轮询一次状态(标签页隐藏时暂停),运行状态变化会自动反映到界面。

共享配置

  • 可编辑监听端口、访问前缀、全局只读,以及每个挂载点的名称、真实目录、 是否按账号隔离、是否只读;

  • 运行中:端口与挂载点输入被锁定,需先停止共享再修改;访问前缀与全局只读支持 热切换,保存后立即生效;

  • 保存成功后立即写回配置文件,界面提示「配置已保存」。

账号管理

  • 列表展示用户名、昵称、权限、状态与创建时间;

  • 新建账号:用户名 + 初始密码 + 昵称 + 权限(「可读写」或「只读」);

  • 启用 / 停用:停用后该账号立即无法通过 WebDAV 认证;

  • 重置密码、修改昵称与权限;

  • 删除账号:立即收回访问权限,但不会删除其私有目录中的已有文件。

设置

  • 外观皮肤:仅保存在当前浏览器的 localStorage,不影响服务端与其它设备;

  • 管理员密码:需输入当前密码;新密码长度 8–128 个字符(按字符计),不能与当前 密码相同。修改成功后会注销该管理员在其它设备上的会话,当前会话保留。

访问共享目录

WebDAV 统一使用 HTTP Basic 认证,账号是「账号管理」中创建的账号,不是管理台管理员。

浏览器

打开 http://<主机>:8081/,输入账号密码后进入目录页。目录页支持:

  • 列表 / 网格视图切换(偏好保存在浏览器本地);

  • 按名称筛选当前目录;

  • 图片、视频缩略图与预览(可左右切换、下载);

  • 拖拽文件到页面直接上传;

  • 新建文件夹、重命名、删除、下载;

  • 只读账号只展示浏览与下载操作。

配置了访问前缀时地址为 http://<主机>:8081/<前缀>/(如 http://<主机>:8081/otter/)。

Windows 资源管理器

  • 地址栏输入:\\192.168.1.10@8081\DavWWWRoot,按提示输入账号密码;

  • 或「映射网络驱动器」→ 文件夹填写 http://192.168.1.10:8081/;

  • 或「添加一个网络位置」按向导填写共享地址。

部分 Windows 版本对 HTTP Basic 或非 443 端口的 WebDAV 有限制,如无法连接可改用 RaiDrive、rclone 等客户端。

macOS

Finder → 「前往」→「连接服务器」(⌘K)→ 输入 http://192.168.1.10:8081/。

Linux

使用 gvfs(文件管理器可直接输入地址)或 davfs2:

sudo mount -t davfs http://192.168.1.10:8081/ /mnt/otter

手机与第三方客户端

RaiDrive、Solid Explorer、Documents、ES 文件浏览器、rclone 等均支持 WebDAV, 填写共享地址与账号密码即可挂载。以下为 rclone 的配置要点:

type = webdav
url  = http://192.168.1.10:8081/
vendor = other
user = icy
pass = <rclone obscure 后的密码>

命令行验证

# 列出根目录下的挂载点
curl -u icy:secret123 -X PROPFIND http://127.0.0.1:8081/ -H 'Depth: 1'

# 上传文件(示例挂载点名为 files)
curl -u icy:secret123 -T ./report.pdf http://127.0.0.1:8081/files/report.pdf

URL 中的非 ASCII 挂载点名需要百分号编码;脚本里建议使用英文挂载点名称。

反向代理子路径

当 nginx / frps 把 https://dav.example.com/otter 转发到本机 8081 时, 请求路径会带上 /otter。此时:

  • 显式设置 share.prefix = /otter;或留空,让程序从 frpc 中localPort == share.port 的 http 代理的 location 自动推导;

  • 程序会剥离该前缀,带前缀与不带前缀的请求都可用(方便局域网直连调试);

  • 目录页里的链接与 PROPFIND 响应中的路径会同步带上前缀,客户端不会拿到错误地址。

管理 HTTP API

管理接口位于同一端口的 /api 下。除 POST /api/login 与 GET /api/session 外, 所有接口都要求已登录:可以携带登录下发的 Cookie,也可以在请求头中使用Authorization: Bearer <token>(登录响应中的 token 字段,便于脚本调用)。

错误统一返回 JSON:{"error": "说明"}。常见状态码:

  • 401:未登录或登录已过期;

  • 403:只读账号 / 只读挂载点写入被拒(WebDAV 侧);

  • 404:账号或路径不存在;

  • 409:共享已在运行 / 未运行、运行中修改端口或挂载点、账号名已存在;

  • 400:请求体或参数不合法。

方法路径说明
POST/api/login登录,返回 username / expiresAt / token,并下发会话 Cookie
GET/api/session查询当前登录态(公开接口)
POST/api/logout注销当前会话
GET/api/status完整状态:共享运行状态、地址、挂载点、账号数、配置路径
GET/api/config配置视图(管理员部分不含密码,共享部分完整)
POST/api/admin/password修改管理员密码:{"currentPassword","newPassword"}
GET/api/share返回 {share, status}
POST/api/share修改共享配置:port / prefix / readonly / mounts 任选
POST/api/share/start启动共享,可选 {"port": 8081}
POST/api/share/stop停止共享
POST/api/share/restart使用当前配置重启共享
GET/api/users账号列表 {users, count}
POST/api/users新建账号,返回 201 与 {user}
PUT/api/users/:id修改账号(password / nickname / description / permission / enabled)
DELETE/api/users/:id删除账号(保留文件)

示例(bash / curl):

BASE=http://127.0.0.1:18761

# 登录并保存 Cookie
curl -s -c cookie.txt -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"qwertyuiop"}' "$BASE/api/login"

# 查询状态
curl -s -b cookie.txt "$BASE/api/status"

# 新建一个可读写账号
curl -s -b cookie.txt -H 'Content-Type: application/json' \
  -d '{"username":"icy","password":"secret123","permission":1}' "$BASE/api/users"

# 修改访问前缀(运行中也可热切换)
curl -s -b cookie.txt -H 'Content-Type: application/json' \
  -d '{"prefix":"/otter"}' "$BASE/api/share"

使用 Bearer 令牌(需要 jq):

TOKEN=$(curl -s -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"qwertyuiop"}' "$BASE/api/login" | jq -r .token)
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/api/status"


安全说明

  • 管理接口默认只监听 127.0.0.1,不开放 CORS;如需远程管理,请置于 HTTPS 反向代理 之后,并限制访问来源;

  • 管理会话仅存内存,Cookie 为 HttpOnly + SameSite=Strict,进程重启即失效; 修改管理员密码会注销该账号在其它设备上的会话;

  • 管理台密码与 WebDAV 账号密码均以 SHA256 十六进制哈希保存,校验使用常量时间比较; SHA256 不是抗暴力破解的慢哈希,请务必使用高熵密码;

  • 配置文件以 0600 权限保存(Unix 上生效,Windows 上受文件系统 ACL 控制), 采用「临时文件 + 原子 rename」,避免半截配置;

  • 路径隔离:账号名禁止 / \ : 与控制字符;虚拟根只暴露挂载点;未知顶层路径 返回 404;跨挂载点 MOVE / COPY 被拒绝;虚拟根与挂载点本身不可删除或覆盖;

  • 服务本身不提供 HTTPS。需要加密传输时请使用 nginx / Caddy 等反向代理, 并视情况设置 share.prefix;

  • 共享端口默认监听所有网卡(未配置 BindHost),请只在可信网络开放, 或通过系统防火墙限制来源。

常见问题

配置文件在哪里?

按「配置文件位置与查找顺序」确定;登录管理台后,状态面板也会显示当前配置文件路径。

忘记管理员密码怎么办?

停止进程,编辑 config.cfg:把 admin.password 改成新的明文密码(重启后会自动转为 哈希并写回),或清空该值让程序随机生成并在启动日志中输出一次,然后重启进程。

修改端口 / 挂载点提示「需要先停止共享」?

运行中修改这些参数会中断所有已连接客户端,因此必须先停止共享再保存。 访问前缀与全局只读不受此限制,可随时热切换。

启动失败提示端口占用?

修改 share.port 或 admin.port;同时确认没有残留的旧进程(单实例锁文件位于系统 临时目录 otter-webdav.lock)。

浏览器能打开目录页,但 Windows 映射网络驱动器失败?

尝试 \\主机@端口\DavWWWRoot 形式;部分 Windows 版本限制 HTTP Basic 或非 443 端口, 可改用 RaiDrive、rclone 等客户端。

上传提示 403 / 只读?

依次检查 share.readonly、对应挂载点的 readonly、账号的 permission 与enabled 状态;只读账号仍可浏览和下载。

修改前端页面后没有生效?

go:embed 打包的是 web/dist,请在 web 目录执行 npm run build,再重新go build / 运行构建脚本。

frpc 没有连上?

确认 frpc.enable = true、serverAddr 正确、token 匹配,且至少配置了一个代理; frpc 只在共享启动成功后接入,启动共享后查看控制台日志中的提示。

删除账号后文件还在?

这是设计行为:删除账号只收回访问权限,不会删除其私有目录中的文件。

可以直接在配置里写明文密码吗?

admin.password 可以(启动时自动转为 SHA256 并写回);users[].password必须是 SHA256 哈希,请通过管理台创建账号或重置密码。

版本与反馈

  • 当前版本 0.1.0

  • 启动横幅中的 QQ 群:73978363

otter-0.1.0.zip
类型:压缩文件|已下载:0|下载方式:免费下载
立即下载
文章版权及转载声明

作者:icy本文地址:https://www.zelig.cn/my/1496.html发布于 昨天
文章转载或复制请以超链接形式并注明出处软角落-SoftNook

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

微信扫一扫打赏

阅读
分享

发表评论

快捷回复:

评论列表 (暂无评论,29人围观)参与讨论

还没有评论,来说两句吧...