Huly Front 服务深度解析静态资源分发、图片预览缩放与 Blob 存储网关【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platform导读本文基于 Huly 仓库 server/front/readme.md 及 server/front 目录下的完整源码深入讲解 Front 服务在 Huly 平台中的三重职责投递前端应用包与静态资源、作为图片预览的缩放/转码服务resize/recode、以及承担 Blob 存储的前端网关操作。读者阅读后将掌握 Front 服务的全部环境变量含义、/files接口的变量占位符语义、图片预览的协商式缩放原理以及如何在本地/开发环境正确对接生产环境。Front 服务在 Huly 架构中的定位在 Huly 的微服务架构中Front 服务是用户浏览器首先到达的入口之一。根据 server/front/readme.md 的概述它承担三类核心职责应用包与资源投递托管编译后的前端 bundleJS/CSS/字体/图标等并支持 gzip 预压缩文件预览图片的 resize/recode根据客户端Accept头与size参数用 sharp 对图片进行缩放与格式转码Blob 存储前端操作提供文件的GET/HEAD/POST/DELETE网关对接底层对象存储如 MinIO/S3实现上传、下载、范围读取与删除。从实现上看服务入口为 server/front/src/__start.ts它创建MeasureMetricsContext后调用 server/front/src/starter.ts 中的startFront完成配置装配最终由 server/front/src/index.ts 的start函数启动 Express 服务并注册全部路由。配置详解环境变量全表server/front/readme.md 列出的核心环境变量如下表。注意除SERVER_PORT与存储相关变量外多数 URL 变量为必填缺失时服务会直接打印错误并process.exit(1)见 server/front/src/starter.ts。环境变量含义必填默认值 / 备注SERVER_PORT服务监听端口否8080parseInt(process.env.SERVER_PORT ?? 8080)MONGO_URLMongoDB 连接串视存储配置由storageConfigFromEnv()组装存储适配器时使用ACCOUNTS_URLaccounts 服务地址是缺失直接退出另有可选ACCOUNTS_URL_INTERNAL供内部调用UPLOAD_URL文件上传地址是缺失直接退出GMAIL_URLGmail 服务地址是缺失直接退出CALENDAR_URLcalendar 服务地址是缺失直接退出TELEGRAM_URLTelegram 服务地址是缺失直接退出REKONI_URLRekoni 服务地址是缺失直接退出COLLABORATOR_URLcollaborator 服务地址是另有可选COLLABORATOR内网地址MODEL_VERSION要求的模型版本号是缺失直接退出会写入/config.jsonSERVER_SECRET服务端密钥是通过setMetadata(serverToken.metadata.Secret, ...)注入 token 校验BRANDING_URLbranding 服务地址否可选仅接受绝对 URL非法时打印Invalid branding URL并忽略此外starter.ts还读取并支持以下可选变量用于/config.json的透传FILES_URL、PREVIEW_URL、PULSE_URL、PUSH_PUBLIC_KEY、LINK_PREVIEW_URL、STREAM_URL、DISABLE_SIGNUP、HIDE_LOCAL_LOGIN、MAIL_URL、BILLING_URL、PAYMENT_URL、HULYLAKE_URL、DATALAKE_URL。其中FILES_URL在未显式设置时的默认值是${uploadUrl}/:workspace/:filename?file:blobIdworkspace:workspace从源码结构看server/front/src/starter.ts该默认值保证了即使未配置FILES_URL/files相关的客户端存储操作也能回退到上传地址派生。启动方式与最小运行示例入口与装配流程server/front/src/__start.ts创建度量上下文并调用startFrontserver/front/src/starter.ts解析环境变量 → 校验必填项 →storageConfigFromEnv()构建存储配置 →buildStorageFromConfig()构建存储适配器 → 启动 Express 并注册SIGINT/SIGTERM优雅关闭。run.sh 最小示例仓库提供了 server/front/run.sh展示本地启动的最小配置#!/usr/bin/env bash export ACCOUNTS_URLhttp://localhost:3333 export UPLOAD_URLhttp://localhost:3333/files export MINIO_ENDPOINTminio export MINIO_ACCESS_KEYminioadmin export MINIO_SECRET_KEYminioadmin node ./bundle/bundle.js可见存储层由MINIO_*系列环境变量驱动经hcengineering/server-storage的storageConfigFromEnv()解析这也是 readme 中MONGO_URL在实际部署中与 MinIO/S3 适配器搭配使用的典型形态。部署时请按上文表格补齐所有必填变量否则服务将拒绝启动。核心 HTTP 接口与变量占位符变量语义server/front/readme.md 定义了以下 URL 模板变量:workspace当前工作区的公开 URL 名称段即 workspace URL 段。在客户端存储客户端中它会被替换为 workspace 的uuid见 foundations/core/packages/api-client/src/storage/client.ts 的connectStorageconfig.FILES_URL.replace(:workspace, token.workspaceId):blobId唯一的 Blob_id标识符:size数值决定图片缩放后的目标尺寸。图片只做缩小、不做放大传-1时使用原图尺寸源码中进一步被解释为2048的上限值见下文:downloadFile完整下载 URI 的 URL-encoded 组件值可以是 S3 存储的 presigned URI。/files 路由族server/front/src/index.ts 注册了以下路由GET /files、GET /files/*读取 Blob支持HEAD支持Range范围请求POST /files、POST /files/*上传表单字段名为file成功返回[{ key, id, metadata: { name, etag, size, contentType, lastModified } }]DELETE /files、DELETE /files/*删除指定?file的 Blob。所有请求都要求携带 token优先级presentation-metadata-TokenCookie →?token查询参数 →Authorization: Bearer ...并会调用 accounts 服务校验工作区身份。若请求路径中的 workspace UUID 与 token 不匹配返回403。图片预览缩放resize/recode 原理触发条件与协商流程filesHandler在处理 GET 时server/front/src/index.ts按以下条件决定是否走预览缩放管线Blob 的contentType为image/*或application/octet-stream原始格式不是image/gif请求携带size参数且Accept头存在。满足条件后调用getGeneratePreviewserver/front/src/index.ts从Accept头解析出客户端支持的图片格式supportedFormats [avif, webp, heif, jpeg, png]按顺序匹配第一个size -1时按2048处理且size 2048一律收敛到2048保证不放大缩放使用 sharprotate()依据 EXIF 自动校正方向resize({ width: size, fit: cover, withoutEnlargement: true })实现只缩不放按协商格式编码jpegprogressive、avif、heif、webp、pngeffort均取 0 以换取速度输出通过sizeId uuid %preview%${size}${format ! jpeg ? format : }命名并回写对象存储下次相同请求直接命中缓存stat命中且size 0即返回实现一次转码、长期复用任何异常都会降级返回原始 Blob保证前端可用性。默认预览 variantreadme 指出当未指定任何 preview 配置时会使用一个默认 variant目标指向 Front 服务自身的 preview/resize 能力/files/${getCurrentWorkspaceUrl()}?file:blobIdsize:size该模板把 workspace URL 段、Blob ID 与目标尺寸拼接到/files路径上与上文filesHandler中req.params.file ?? req.query.file的取值逻辑server/front/src/index.ts一一对应即既支持路径段形式也支持?file查询参数形式。providerName 通配readme 同时说明providerName 可设置为*此时表示该 provider 为默认 preview providerdefault preview provider。从源码结构看这与 preview 相关配置在 URL 模板层面合并处理的设计一致——*作为一个通配 provider 名命中时即回退到上述 Front 服务的默认 preview/resize 能力。下载型 URIdownloadFile与开发环境注意事项readme 中Testing with dev-production/etc.一节给出了重要实操约束当应用运行在 localhost 时只有downloadFile变体的 URI 能正常工作因为生产环境的 preview 请求需要有效的 token 校验而本地开发环境下无法为 preview/resize 请求提供可通过校验的授权凭证。因此在本地联调生产环境的实践中优先构造完整的下载 URI并将目标文件 URI 做 URL-encoded 后填入:downloadFile占位符该值也可以是 S3 的 presigned URI避免在 localhost 直接依赖默认 preview variant 访问生产对象存储否则会遇到 token 校验失败401/403。深入源码静态分发、缓存与条件请求静态资源投递start函数中静态目录为PUBLIC_DIR ?? cwd()下的distserver/front/src/index.ts使用express-static-gzip提供 gzip 预压缩文件缓存策略普通静态资源Cache-Control: public, no-cache, must-revalidate, max-age365d配合 ETag/Last-Modifiedindex.html或 branding 路径public, no-store, no-cache, must-revalidate, max-age0保证每次拉取最新入口兜底路由server/front/src/index.ts对.js/.css/.woff/.svg/.png/.avif等扩展返回 404交由真正的静态资源服务其余 SPA 路径回退到index.html并通过normalize(join(dist, path))做路径穿越防护。条件请求与范围请求server/front/src/utils.ts 实现了完整的 HTTP 条件请求原语If-Match/If-None-Match/If-Modified-Since/If-Unmodified-Since支持弱/强 ETag。在getFile中server/front/src/index.ts命中If-None-Match等条件时返回304 Not Modified否则200全量返回getFileRange则解析Range头通过存储适配器的partial接口返回206 Partial Content越界范围返回416。这套实现使 Front 服务天然支持浏览器缓存与音视频/大文件断点续传。可观测性与配置下发GET /config.jsonserver/front/src/index.ts一次性下发ACCOUNTS_URL、UPLOAD_URL、FILES_URL、MODEL_VERSION、VERSION及全部服务地址前端据此动态路由GET /api/v1/statistics携带管理员 token 可读取聚合指标metricsAggregate(...)无效 token 返回401全链路使用MeasureContext埋点morgan请求日志、错误上报均接入hcengineering/analytics连接层面设置keep-alivetimeout 5s / max 1000 连接并同步调整server.keepAliveTimeout/headersTimeout。总结Front 服务是 Huly 前端与对象存储之间的咽喉对内它投递应用包并向下游服务透传配置对外它提供带鉴权、缓存、范围请求与图片协商式缩放的 Blob 网关。理解 server/front/readme.md 中定义的变量占位符:workspace、:blobId、:size、:downloadFile、默认 preview variant 与*通配 provider 语义并对照 server/front/src/index.ts、server/front/src/starter.ts 的源码实现即可在生产部署、本地联调与二次开发中准确驾驭该服务。【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platform创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考