HedgeDoc 使用 WebDAV 作为图片存储后端：环境变量配置与 Nextcloud 实战指南

后端前端云原生【免费下载链接】hedgedocHedgeDoc - Ideas grow better together项目地址https://gitcode.com/gh_mirrors/he/hedgedoc点击查看免费下载HedgeDoc 支持将笔记中的图片上传存储到多种后端本地文件系统、S3、Azure Blob、imgur、WebDAV其中 WebDAV 方案允许你复用任意支持 WebDAV 协议的服务器来托管上传文件。本文将基于仓库文档与源码完整讲解HD_MEDIA_BACKEND_WEBDAV_*三个环境变量的含义与取值规则并以 Nextcloud 为例给出从创建应用密码到验证上传的完整实操步骤。读完本文你可以独立为 HedgeDoc 配置一套基于 WebDAV/Nextcloud 的图片存储服务。一、WebDAV 媒体后端的工作原理在 HedgeDoc 中媒体Media指与笔记关联的上传内容目前仅支持图片。所有存储后端都必须实现同一个接口包含三个方法见 backend/src/media/media-backend.interface.ts 与设计文档 docs/content/concepts/media.mdsaveFile(uuid, buffer, fileType)保存文件并返回一段字符串化的元数据供数据库留存该元数据只在本后端内部使用deleteFile(uuid, metadata)根据 UUID 与元数据删除远端文件getFileUrl(uuid, metadata)返回该文件对外可访问的 URL。对于 WebDAV 后端HedgeDoc 会在启动时通过PROPFIND请求探测目标目录是否可访问见 webdav-backend.ts若请求失败会直接抛错提示Cant access url。因此配置完成并启动后WebDAV 服务器必须允许 HedgeDoc 以配置的凭据访问目标目录。后端的选择在 backend/src/media/media.module.ts 中注册由 MediaService 依据HD_MEDIA_BACKEND_TYPE的值filesystem/azure/imgur/s3/webdav决定实例化哪一个后端。上传时MediaService.saveFile会先对文件做 MIME 类型白名单校验仅允许 apng、bmp、gif、heif/heic、jpeg、png、svg、tiff、webp见 media.service.ts再调用WebdavBackend.saveFile完成写入。二、核心配置三个 WebDAV 环境变量在 HedgeDoc 中所有配置均通过环境变量或根目录.env文件注入。WebDAV 后端只需在配置中加入以下三行CONNECTION_STRING、UPLOAD_DIR、PUBLIC_URL需替换为实际值HD_MEDIA_BACKEND_TYPEwebdav HD_MEDIA_BACKEND_WEBDAV_CONNECTION_STRINGCONNECTION_STRING HD_MEDIA_BACKEND_WEBDAV_UPLOAD_DIRUPLOAD_DIR HD_MEDIA_BACKEND_WEBDAV_PUBLIC_URLPUBLIC_URL对应地仓库中的配置解析backend/src/config/media.config.ts对这三个变量有明确的校验规则这与使用体验直接相关环境变量说明校验要求是否必填HD_MEDIA_BACKEND_TYPE媒体后端类型取webdav时启用本后端必须与五种后端类型之一精确匹配必填HD_MEDIA_BACKEND_WEBDAV_CONNECTION_STRINGWebDAV 服务器的连接地址含身份信息必须是一个合法的 URLzod 的z.string().url()必填HD_MEDIA_BACKEND_WEBDAV_UPLOAD_DIR上传目标目录省略则直接上传到 WebDAV 服务器根目录可选字符串可为空可选HD_MEDIA_BACKEND_WEBDAV_PUBLIC_URLHedgeDoc 对外访问上传文件的 URL 前缀必须是一个合法的 URL必填配置解析使用 zod 校验同文件中z.discriminatedUnion(type, [...])定义一旦HD_MEDIA_BACKEND_TYPE之外的关键值非法或缺失启动时会打印格式化的错误信息并退出避免带病运行。2.1 CONNECTION_STRING连接地址与身份凭据CONNECTION_STRING采用 WebDAV 常见的schema://user:passwordurl形式把用户名与密码如有需要直接内嵌进 URL例如https://TestUser:passw0rdcloud.example.com/remote.php/dav/files/TestUser/从源码看WebdavBackend 会解析该 URL先以完整连接串为基准若同时配置了非空的UPLOAD_DIR则把目录拼接在连接串之后作为最终上传基址随后用url.username与url.password生成 HTTP Basic Auth 请求头Basic base64(username:password)见 webdav-backend.ts。2.2 UPLOAD_DIR指定上传目录可省略UPLOAD_DIR用于指定上传的目标文件夹例如HedgeDoc。它不是必填项——如果不设置即完全不写该变量HedgeDoc 会把文件直接上传到 WebDAV 服务器的根目录。源码中的对应逻辑是仅当uploadDir存在且非空字符串时才拼接目录webdav-backend.ts。2.3 PUBLIC_URL对外访问 URL 前缀PUBLIC_URL指定 HedgeDoc 访问上传文件所用的 URL 前缀。文件名会被直接追加到该前缀之后。例如PUBLIC_URL为https://dav.example.com、文件名为test.png时访问地址即为https://dav.example.com/test.png。这与源码行为完全一致getFileUrl 从数据库元数据中取出文件名再将其拼接到publicUrl之后返回MediaService.getFileResponse 对 WebDAV 这类后端返回{ type: redirect, url }由媒体重定向控制器backend/src/media-redirect/media-redirect.controller.ts将浏览器 302 到该地址。因此PUBLIC_URL必须指向一个能让浏览器直接下载到图片的公开地址。三、上传与删除的底层行为理解后端的 HTTP 细节有助于排查故障。WebdavBackend内部使用fetch与 WebDAV 服务器交互上传saveFile以PUT方法请求baseUrl/uuid.扩展名携带Authorization、Content-Type: application/octet-stream与准确的Content-Length并设置If-None-Match: *头保证不会覆盖已存在的文件见 webdav-backend.ts。上传成功后后端把{file:uuid.ext}这样的 JSON 字符串作为 backendData 写入数据库的media_upload表删除deleteFile以DELETE方法请求baseUrl/文件名见 webdav-backend.ts访问getFileUrl如上所述仅拼接publicUrl与文件名不发起请求。需要特别注意的是CONNECTION_STRING中携带的用户名/密码会出现在配置文件里因此官方文档建议为上传单独创建一个专用 WebDAV 用户并尽量使用应用密码App Password而不是主密码。四、Nextcloud 实战配置完整步骤以 Nextcloud 作为 WebDAV 服务器是最常见的用法。以下步骤以 Nextcloud 212021 年 4 月撰写指南时的版本为例演示用户名为TestUser、生成的应用密码为passw0rd的完整配置链路。由于连接串中包含用户名与密码强烈建议使用一个专用 Nextcloud 用户来承担上传任务。创建应用密码登录 Nextcloud 后进入SettingsSecurity由 Nextcloud 生成一个应用密码本例假设为passw0rd。创建上传文件夹在文件Files应用中新建一个文件夹用于存放上传内容例如HedgeDoc。共享该文件夹右键/菜单共享刚创建的文件夹。默认配置为Read Only只读本指南按此假设展开选择Allow upload and editing允许上传和编辑同样可行。获取共享链接创建共享后链接通常已在剪贴板否则点击Share link一行末尾的剪贴板图标复制。本例假设共享链接为https://cloud.example.com/s/some-id。拼接下载参数在该链接末尾追加/download?path%2Ffiles得到https://cloud.example.com/s/some-id/download?path%2Ffiles。这正是之后PUBLIC_URL的取值HedgeDoc 会把文件名追加到其后使图片通过共享链接的下载端点对外提供。获取 Nextcloud 的 WebDAV 地址在文件应用的左下角位于SettingsWebDAV处。本例假设为https://cloud.example.com/remote.php/dav/files/TestUser/。拼入登录信息在 URL 协议通常是https://与 URL 其余部分本例为cloud.example.com/remote.php/dav/files/TestUser/之间插入username:password得到https://TestUser:passw0rdcloud.example.com/remote.php/dav/files/TestUser/。这就是CONNECTION_STRING。配置 HedgeDocHD_MEDIA_BACKEND_TYPEwebdav HD_MEDIA_BACKEND_WEBDAV_CONNECTION_STRINGhttps://TestUser:passw0rdcloud.example.com/remote.php/dav/files/TestUser/ HD_MEDIA_BACKEND_WEBDAV_UPLOAD_DIRHedgeDoc HD_MEDIA_BACKEND_WEBDAV_PUBLIC_URLhttps://cloud.example.com/s/some-id/download?path%2Ffiles完成上述配置后重启 HedgeDoc 服务即可开始使用由 Nextcloud WebDAV 支撑的图片上传上传时文件以uuid.扩展名的命名写入TestUser的HedgeDoc目录笔记中的图片通过共享链接的下载地址对外展示。五、验证与常见问题启动即验证WebdavBackend构造时会对baseUrl发起一次PROPFINDDepth: 0请求非 2xx 响应或网络失败都会导致启动报错Cant access url。若服务起不来优先检查连接串的协议、主机、目录与凭据。PUBLIC_URL 必须可公开访问它仅用于拼 URLHedgeDoc 自身不代理图片字节流而是返回 302 重定向。请确认浏览器可以直接访问PUBLIC_URL 文件名。文件不会被覆盖上传请求带If-None-Match: *同名文件UUID 冲突会失败而不是覆盖确保历史图片引用不被破坏。目录与凭据的转义用户名、密码若含、:、/等特殊字符需按 URL 编码规则转义否则 URL 解析与 Basic Auth 会出错。配置格式要求CONNECTION_STRING与PUBLIC_URL必须是合法 URLUPLOAD_DIR可省略若省略上传目录文件将落在 WebDAV 服务器根目录。六、相关资源官方文档docs/content/references/config/media/webdav.md本文的原始依据配置解析与校验backend/src/config/media.config.tsWebDAV 后端实现backend/src/media/backends/webdav-backend.ts媒体后端统一接口backend/src/media/media-backend.interface.ts媒体服务与后端选择逻辑backend/src/media/media.service.ts后端注册backend/src/media/media.module.ts媒体设计文档docs/content/concepts/media.md环境变量总体说明docs/content/references/config/index.md赞分享后端前端云原生【免费下载链接】hedgedocHedgeDoc - Ideas grow better together项目地址https://gitcode.com/gh_mirrors/he/hedgedoc点击查看免费下载相关推荐使用 S3 兼容对象存储作为 HedgeDoc 图片上传后端环境变量配置与源码实现全解析使用 S3 兼容对象存储作为 HedgeDoc 图片上传后端环境变量配置与源码实现全解析 本文以 HedgeDoc 官方配置文档 docs/content/r后端前端云原生HedgeDoc 图片上传存储配置指南使用本地文件系统Filesystem作为媒体后端HedgeDoc 图片上传存储配置指南使用本地文件系统Filesystem作为媒体后端 HedgeDoc 支持将笔记中上传的图片保存到多种存储后端其中最后端前端云原生HedgeDoc 使用 Imgur 作为图片上传后端配置指南与源码原理HedgeDoc 使用 Imgur 作为图片上传后端配置指南与源码原理 导读 HedgeDoc 将笔记中上传的图片Media统一交由可插拔的存储后端处理后端前端云原生上一篇sd-forge-layerdiffusion开发者指南代码架构与自定义扩展开发下一篇代码辅助every-chatgpt-gui专为开发者设计的ChatGPT界面创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考