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/ 登录管理台,即可启停共享、配置挂载点、管理账号。
首次启动与默认密码
配置文件不存在时自动生成默认配置:管理员账号
admin、密码为空, 启动时随机生成 16 位密码并只在控制台输出一次;共享默认不自动开启 (share.enabled = false),默认挂载点为share/<用户名>(perUser = true)。仓库自带的示例
bin/config.cfg:管理员为admin,密码为qwertyuiop(配置中保存的是其 SHA256 哈希)。正式使用前请登录管理台,在「设置 → 管理员密码」 中修改。管理台会话只保存在内存,进程重启后需要重新登录;配置文件以
0600权限原子写盘, 只有密码哈希,不保存管理台明文密码。
配置文件
位置与查找顺序
程序按以下优先级确定配置文件:
命令行参数
-config <路径>;环境变量
OTTER_CONFIG;可执行文件同目录下的
config.cfg(存在时);当前工作目录下的
config.cfg(存在时);可执行文件同目录下的
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 段
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
host | string | 127.0.0.1 | 管理接口监听地址,默认只允许本机访问 |
port | int | 18761 | 管理接口端口 |
user | string | admin | 管理员账号 |
password | string | 空 | SHA256 哈希;也可直接写明文,启动时自动转换并写回。为空时启动随机生成 16 位密码并只打印一次 |
sessionHours | int | 12 | 登录会话有效期(小时),上限 30 天 |
share 段
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
dir | string | share | 默认共享根目录,仅在未配置挂载点时用于生成默认私有挂载点 |
port | int | 8081 | WebDAV 监听端口(共享端口) |
enabled | bool | 新配置为 false | 进程启动时是否自动开启共享 |
readonly | bool | false | 全局只读,所有账号、所有挂载点都不可写 |
prefix | string | 空 | 反向代理子路径前缀,如 /otter;空表示根路径 |
mounts[].name | string | 我的文件 | WebDAV 顶层虚拟目录名,必须唯一 |
mounts[].path | string | share | 真实目录;相对路径按配置文件目录解析 |
mounts[].perUser | bool | 默认挂载点为 true | true 时映射到 <path>/<用户名>;false 时所有账号共享 <path> |
mounts[].readonly | bool | false | 该挂载点对所有人只读(即使账号有写权限) |
挂载点与路径语义:
虚拟根
/只列出配置的挂载点,不允许写入、删除、重命名或移动;/<挂载点>/...映射到真实目录,未知的顶层名称一律视为不存在(404);不允许跨挂载点
MOVE/COPY,避免在不同账号目录之间搬运文件;挂载点名称不能为空、不能是
./..、不能包含/或\,且不能重复;至少保留一个挂载点;启动时会自动创建缺失的挂载点目录。
只读判定从严格到宽松依次是:
share.readonly = true:全局只读,任何人不可写;mounts[].readonly = true:该挂载点不可写;账号
permission = 0或enabled = false:该账号不可写 / 无法认证;其余情况可写(
permission = 1且账号已启用)。
users 段
通常由管理台维护,无需手工编辑。字段与账号模型一致:
| 键 | 类型 | 说明 |
|---|---|---|
id | int | 账号 ID,自动分配 |
username | string | 登录名,同时作为私有目录名。不能为空、不超过 64 字节、不能是 . / ..、不能以 . 开头、不能包含 / \ : 或控制字符 |
password | string | SHA256 十六进制哈希(64 字符)。手写明文不会被自动转换,请通过管理台创建账号或重置密码 |
nickname | string | 昵称,仅用于展示 |
description | string | 备注 |
permission | int | 0 只读,1 可读写(其他值按可读写处理) |
enabled | bool | 是否启用;停用后立即无法通过 WebDAV 认证 |
createdAt | int | 创建时间(Unix 秒),为 0 时自动补当前时间 |
删除账号不会删除其私有目录中的文件,只是立即收回访问权限;需要清理数据时请手动处理。
frpc 段
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
enable | bool | false | 是否在共享启动后接入 frps |
serverAddr | string | 空 | frps 地址;为空则跳过接入 |
serverPort | int | 7000 | frps 服务端口 |
token | string | 空 | frps 认证令牌 |
proxies[].name | string | 必填 | 代理名称,需在 frps 侧唯一 |
proxies[].type | string | http | http 或 tcp |
proxies[].localIP | string | 127.0.0.1 | 本地服务地址 |
proxies[].localPort | int | 必填 | 本地端口,通常等于 share.port |
proxies[].remotePort | int | 0 | tcp 类型映射到 frps 的端口 |
proxies[].domain | string | 空 | http 类型按 Host 路由的域名 |
proxies[].subDomain | string | 空 | 或使用 frps 的 subdomain_host |
proxies[].location | string | 空 | 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





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