后端前端云原生【免费下载链接】hedgedocHedgeDoc - Ideas grow better together项目地址https://gitcode.com/gh_mirrors/he/hedgedoc点击查看免费下载HedgeDoc 允许将笔记中的图片上传到多种外部存储后端Microsoft Azure Blob Storage 是官方支持的可选后端之一。本文以 Azure Blob Storage 配置文档 为核心完整讲解从获取连接字符串、创建容器到写入环境变量配置的每一步并结合 media.config.ts 与 azure-backend.ts 源码说明配置参数如何被校验、文件如何上传与访问。读完本文你将能独立为 HedgeDoc 接入 Azure Blob Storage并理解其底层调用链与常见坑点。一、接入前的两项准备工作在配置 HedgeDoc 之前你需要在 Azure 侧完成两件事获取存储账户Storage Account的连接字符串以及创建一个访问级别为 publicblob的容器Container。1. 获取存储账户连接字符串连接字符串connection string包含了存储账户的访问凭据信息是 HedgeDoc 后端与 Azure Blob 服务建立连接的核心凭证。你可以在 Azure 门户中找到存储账户在其访问密钥Access keys页面中复制连接字符串。从源码看这条连接字符串会被直接传给 Azure SDK 的BlobServiceClient.fromConnectionString()来初始化客户端见 azure-backend.ts因此其格式必须符合 Azure 官方规范。2. 创建公开可读的容器容器是存放 Blob 的顶层目录HedgeDoc 上传的图片最终都会以 UUID 命名存放在这个容器中。官方文档要求容器访问级别public access level设置为blob即允许通过匿名请求读取容器内的 Blob。你可以使用 Azure CLI 创建容器命令如下注意把NAME替换为容器名、CONNECTION_STRING替换为你的连接字符串az storage container create --name NAME --public-access blob --connection-string CONNECTION_STRING其中--name NAME指定容器名称需要与后续环境变量HD_MEDIA_BACKEND_AZURE_CONTAINER中的值完全一致--public-access blob将容器的公共访问级别设置为 blob容器本身不可匿名列出但容器内的 Blob 可匿名读取--connection-string传入从 Azure 门户获取的连接字符串。如果你更习惯图形界面也可以在 Azure 门户中直接创建容器并在容器的访问级别选项中选择Blob仅限匿名读取 Blob。两种方式效果等价按需选择即可。二、写入 HedgeDoc 环境变量配置准备工作完成后只需在 HedgeDoc 的配置环境变量或.env文件中添加三行配置。HedgeDoc 通过环境变量进行配置既可以直接设置在系统环境中也可以写入项目根目录下的.env文件在官方 Docker 镜像中.env文件的默认位置是/usr/src/app/.env参见 配置总览文档。HD_MEDIA_BACKEND_TYPEazure HD_MEDIA_BACKEND_AZURE_CONNECTION_STRINGCONNECTION_STRING HD_MEDIA_BACKEND_AZURE_CONTAINERNAME三个变量的含义如下环境变量必填说明HD_MEDIA_BACKEND_TYPE是媒体存储后端类型固定为azure。可选值包括filesystem、s3、imgur、webdav、azure定义见 media-backend-type.enum.tsHD_MEDIA_BACKEND_AZURE_CONNECTION_STRING是Azure 存储账户连接字符串HD_MEDIA_BACKEND_AZURE_CONTAINER是存放图片的容器名称须与前面创建容器时使用的NAME一致配置校验缺一不可错误即退出这三项配置并不是填了就行后端会严格校验。在 media.config.ts 中Azure 后端的配置通过 zod 模式定义为const azureSchema z.object({ type: z.literal(MediaBackendType.AZURE), azure: z.object({ connectionString: z.string().describe(HD_MEDIA_BACKEND_AZURE_CONNECTION_STRING), container: z.string().describe(HD_MEDIA_BACKEND_AZURE_CONTAINER), }), });这意味着HD_MEDIA_BACKEND_TYPE的值必须是azure否则校验失败connectionString与container都是必填字符串缺失或为空都会触发配置错误校验失败时后端会打印错误信息并直接退出进程printConfigErrorAndExit见 media.config.ts而不是带着错误配置继续运行。此外还有一个可选的全局参数HD_MEDIA_MAX_UPLOAD_SIZE单位为字节用于限制上传文件的最大体积默认值为 20 MB20 * 1024 * 1024见 media.config.ts。它在 media.config.ts 中定义为可选项如果你不设置就使用默认值。完整的.env示例下面是一个加入了 Azure 配置的最小化.env示例其余变量按你的实际部署环境填写HD_BASE_URLhttp://localhost:8080 HD_SESSION_SECRETchange_me_in_production HD_DATABASE_TYPEsqlite HD_DATABASE_NAME./hedgedoc.sqlite HD_MEDIA_BACKEND_TYPEazure HD_MEDIA_BACKEND_AZURE_CONNECTION_STRINGDefaultEndpointsProtocolhttps;AccountNameyouraccount;AccountKeyyourkey;EndpointSuffixcore.windows.net HD_MEDIA_BACKEND_AZURE_CONTAINERhedgedoc-images需要注意的是接入 Azure 后端后上传的图片将不再存放在本地磁盘而是全部写入你的 Azure 容器因此请确保容器所在区域与你的用户访问路径之间网络可达并妥善保管连接字符串它等同于存储账户的访问密钥。三、后端实现原理从配置到文件的完整链路理解了配置项之后我们来看 HedgeDoc 后端实际是如何使用这些配置的。这能帮助你判断配置是否正确以及排查上传失败的问题。MediaBackend 统一接口HedgeDoc 为所有存储后端定义了一个统一的接口 MediaBackend每个后端只需实现三个方法saveFile(uuid, buffer, fileType)保存文件返回可选的内部元数据Azure 后端返回nulldeleteFile(uuid, backendData)按 UUID 删除文件getFileUrl(uuid, backendData)返回文件的公开访问 URL可以是临时 URL。Azure 后端就是这三个方法的实现之一与 Filesystem、S3、Imgur、WebDAV 后端并列全部实现位于 backend/src/media/backends 目录各后端的配置文档见 media 配置目录。AzureBackend 的初始化与连接建立在 azure-backend.ts 的构造函数中后端会检查mediaConfig.backend.type是否为azure否则直接返回避免在未启用 Azure 时产生无用的连接用连接字符串调用BlobServiceClient.fromConnectionString(this.config.connectionString)创建服务客户端通过blobServiceClient.getContainerClient(this.config.container)拿到容器客户端——注意这里使用的正是HD_MEDIA_BACKEND_AZURE_CONTAINER的值。因此连接字符串无效或容器名称不存在都会在这一步直接导致后端初始化失败。上传saveFile 的完整流程当用户在编辑器里上传一张图片时MediaService.saveFile 会依次执行使用extractFileType检测文件真实类型并对照 MIME 类型白名单校验——目前允许的类型包括image/png、image/jpeg、image/gif、image/webp、image/svgxml等常见图片格式见 media.service.ts不匹配的类型直接拒绝生成一个 UUID v7 作为文件的唯一标识见 media.service.ts调用AzureBackend.saveFile(uuid, buffer, fileType)真正上传。Azure 端的saveFile实现见 azure-backend.ts逻辑很直接通过容器客户端拿到以 UUID 命名的 Block Blob然后调用blockBlobClient.upload(buffer, buffer.length, { blobHTTPHeaders: { blobContentType: fileType.mime } })上传并把 Blob 的 Content-Type 设置为检测到的 MIME 类型确保图片在浏览器中以正确的类型被渲染。上传成功后写入日志Uploaded file uuid失败则抛出MediaBackendError。访问重定向 1 小时有效期的 SAS URL图片的读取路径与本地文件系统后端不同。在 MediaService.getFileResponse 中当数据库记录的backendType不是filesystem时服务会调用getFileUrl(uuid, backendData)拿到一个 URL并以HTTP 重定向的方式把请求导向该 URL。Azure 端的getFileUrl实现见 azure-backend.ts会通过generateBlobSASQueryParameters生成一个SAS共享访问签名令牌其关键行为是权限固定为r只读BlobSASPermissions.parse(r)有效期固定为1 小时expiresOn为当前时间 3600 * 1000毫秒最终 URL 形如blobUrl?SAS参数。这意味着即使你按官方文档把容器设置为 publicblob访问级别后端返回给浏览器的仍是一个带时效的 SAS 签名 URL。从源码结构可以推断这样的设计让 URL 具备临时性避免长期暴露完整的直链如果 1 小时后再访问同一个签名 URL链接会失效但 HedgeDoc 每次请求图片时都会重新生成新 URL因此正常使用不受影响。删除deleteFile当图片被移除时MediaService.deleteFile 会先根据 UUID 从数据库查出上传记录再调用AzureBackend.deleteFile见 azure-backend.ts删除对应的 Block Blob最后清理数据库记录。如果 Azure 返回了错误码如 Blob 不存在后端会抛出MediaBackendError。后端注册与选择AzureBackend作为 provider 注册在 media.module.ts 中与其余四个后端一起由MediaService按需获取。MediaService启动时会读取HD_MEDIA_BACKEND_TYPE决定使用哪个后端见 media.service.ts并在后续每一次读写图片时按数据库中记录的backendType选择对应实现。整个媒体存储的架构设计可参考 Media 设计文档。四、验证配置与常见问题排查如何确认配置生效修改配置后重启 HedgeDoc 后端进程Docker 部署则重启容器。如果配置校验失败进程会打印错误并退出日志中会明确指出哪个环境变量缺失或非法。在任意笔记编辑器中拖入一张图片上传成功后编辑器预览区域应显示图片。浏览器开发者工具中图片请求应返回302 重定向目标地址是https://你的存储账户.blob.core.windows.net/容器名/uuid?sv...sig...形式的 SAS URL——这与你之前使用的filesystem后端直接流式返回文件内容HTTP 200不同可作为判断后端是否切换成功的直观信号。常见问题进程启动即报配置错误检查三个环境变量是否都已设置、HD_MEDIA_BACKEND_TYPE是否精确为小写azure。图片上传失败 / 日志出现Could not save file多为连接字符串无效、容器不存在或容器所在存储账户的密钥权限不足核对 azure-backend.ts 中使用的连接字符串与容器名。图片上传后被拒绝HedgeDoc 有 MIME 类型白名单见 media.service.ts请确认上传的是白名单内的图片格式。通过签名 URL 直接访问 404/过期SAS 有效期仅 1 小时见 azure-backend.ts请通过 HedgeDoc 页面重新访问以获取新生成的 URL。与其他后端的选型提示如果你的部署环境不便使用 AzureHedgeDoc 同样支持将图片存入 本地文件系统、S3 兼容存储、Imgur 或 WebDAV切换方式都遵循同样的模式修改HD_MEDIA_BACKEND_TYPE并补充对应后端的专属环境变量。选择 Azure Blob Storage 的优势在于其高可用托管存储适合希望图片与本地磁盘解耦、需要持久化与扩容保障的部署场景。五、小结接入 Azure Blob Storage 只需要三步在 Azure 侧拿到连接字符串并创建 publicblob容器把HD_MEDIA_BACKEND_TYPE、HD_MEDIA_BACKEND_AZURE_CONNECTION_STRING、HD_MEDIA_BACKEND_AZURE_CONTAINER写入 HedgeDoc 环境变量然后重启服务。后端会通过 zod 模式严格校验这三项配置并由 AzureBackend 基于 Azure SDK 完成上传、删除与 1 小时有效期的 SAS 签名 URL 生成。理解了这条链路无论是首次接入还是后续排障都能事半功倍。赞分享后端前端云原生【免费下载链接】hedgedocHedgeDoc - Ideas grow better together项目地址https://gitcode.com/gh_mirrors/he/hedgedoc点击查看免费下载相关推荐LMCache Azure Blob Storage 后端接入指南从配置到源码级原理解析LMCache Azure Blob Storage 后端接入指南从配置到源码级原理解析 本指南讲解 LMCache 如何通过原生异步 Connector 将人工智能大模型缓存抽象模型推理服务Payload 的 Azure Blob Storage 适配器storage-azure 配置、客户端直传与 CORS 全解析Payload 的 Azure Blob Storage 适配器storage azure 配置、客户端直传与 CORS 全解析 payloadcms/st后端CMSFlynn 中的 Azure Storage SDK for Go从 Blob 后端到飞桨式块级上传的源码级解析Flynn 中的 Azure Storage SDK for Go从 Blob 后端到飞桨式块级上传的源码级解析 导读 本文以 vendor/github.c云原生微服务容器编排运维上一篇InstaEclipse高级技巧让你成为Instagram power user的10个实用功能下一篇终极揭秘如何让撤回的微信QQ消息无所遁形完整防撤回指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考