版本以构建时注入的内置变量为准（运行 media-server -version 查看）。唯一来源：根目录 VERSION 文件。
基于 S3 标准接口（Amazon S3、MinIO、阿里云 OSS 的 S3 兼容端点）的图片/视频处理服务，提供阿里云 OSS 风格的 x-oss-process URL 语法。支持直出（GET/HEAD）、图片缩放/裁剪/格式转换、视频截图与短视频预览，派生内容支持磁盘缓存与强校验 ETag。
重要说明
- 必须安装 ffmpeg（视频功能与部分 WebP 解码回退依赖它）。
- Ubuntu 24.04：
sudo apt-get update && sudo apt-get install -y ffmpeg - 校验：
ffmpeg -version
- Ubuntu 24.04：
- 静态图 WebP 输出默认启用（无需构建标签）。需启用 CGO，并建议安装
libwebp-dev以确保编译/运行环境完整。
快速开始（开发）
- 复制环境模板并修改
cp .env.example dev/.env，填写S3_BUCKET/AWS_*/S3_ENDPOINT等参数。
- （可选）用 Docker Compose 启动本地 MinIO
- 在
minio-dev/目录运行：docker compose -f minio-dev/docker-compose.yml up -d
- 控制台：
http://127.0.0.1:9001（用户名/密码：minioadmin/MediaServer8765） - S3 端点：
http://127.0.0.1:9000，Bucket 自动创建为media-server - 如首次未创建成功，可重试初始化：
docker compose -f minio-dev/docker-compose.yml run --rm minio-init - 数据目录：将在
minio-dev/data/持久化（相对 docker-compose.yml 所在目录）。 - 将
dev/.env中的存储配置设为：S3_BUCKET=media-serverS3_ENDPOINT=http://127.0.0.1:9000S3_USE_PATH_STYLE=true
- 安装系统依赖（至少 ffmpeg；为 WebP 输出建议安装编译工具与 libwebp）
- Ubuntu/Debian：
sudo apt-get update && sudo apt-get install -y ffmpeg build-essential pkg-config libwebp-dev - macOS（Homebrew）：
brew install ffmpeg - Alpine：
apk add --no-cache ffmpeg
- 启动与日志
- 启动：
./dev.sh start - 日志：
./dev.sh logs
- 示例（默认
SERVICE_PATH=media）
- 直出：
http://127.0.0.1:6080/media/cat.jpg - 缩放：
http://127.0.0.1:6080/media/cat.jpg?x-oss-process=image/resize,w_800,h_600,m_lfit - 裁剪+缩放+格式：
http://127.0.0.1:6080/media/cat.jpg?x-oss-process=image/crop,w_500,h_500,g_center/resize,w_300,h_300,m_fill/format,jpg - 视频截图：
http://127.0.0.1:6080/media/clip.mp4?x-oss-process=video/snapshot,t_1000,f_jpg,w_640,h_360,m_fast - 短视频预览：
http://127.0.0.1:6080/media/clip.mp4?x-oss-process=video/preview,t_1000,d_3000,f_mp4,w_320,h_180,m_fast
核心特性
- S3 直出（GET/HEAD），支持 Range/条件请求并透传元信息。
- 图片处理：resize/crop/format；链式处理（
/分隔）。 - 视频处理：snapshot（单帧截图）、preview（短视频预览，静音）。
- 磁盘缓存：派生内容落盘缓存，派生 ETag =
sha256(etag_src + "|" + process + "|v1")，支持If-None-Match命中 304。 - 访问控制：
PUBLIC_TRANSFORM与签名校验；直出RAW_PASSTHROUGH_MODE支持on|signed_only|off。
配置（环境变量要点）
- 监听/路径：
LISTEN_ADDR（默认0.0.0.0:6080）、SERVICE_PATH（默认media）。 - 日志：
LOG_LEVEL、各类超时（READ_*/WRITE_TIMEOUT/IDLE_TIMEOUT）。 - 存储（S3 标准）：
S3_BUCKET、AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_REGION、S3_ENDPOINT、S3_USE_PATH_STYLE。 - 直出策略：
RAW_PASSTHROUGH_MODE=on|signed_only|off；PUBLIC_TRANSFORM=true|false；签名密钥TRANSFORM_SIGN_SECRET与 TTL。 - CORS：
CORS_ENABLED、CORS_ALLOW_*、CORS_EXPOSE_HEADERS、CORS_MAX_AGE_SECONDS。 - 处理：
IMG_ENGINE、FFMPEG_PATH、TRANSFORM_CONCURRENCY、TRANSFORM_TIMEOUT_SECONDS、MAX_IMAGE_PIXELS、MAX_SNAPSHOT_RESOLUTION。 - 缓存：
CACHE_DIR、CACHE_MAX_SIZE_MB、CACHE_TTL_SECONDS、CACHE_CLEAN_INTERVAL、CACHE_WRITE_BACK。 - 详细示例见根目录
.env.example。
更多“路径/查询语法与签名规则”（面向 AGENTS）请见：MEDIA-SERVER-USAGE-AGENTS.md。
WebP 输出（静态图）
- 默认开启：无需
-tags。编码通过github.com/chai2010/webp实现。 - 环境要求：
- 启用 CGO（dev.sh 已默认设置
CGO_ENABLED=1）。 - 若构建时报缺少头文件/库，安装
libwebp-dev（Ubuntu/Debian）。 - 运行时无需额外二进制；仅当处理复杂 WebP 解码回退路径时，可能用到 ffmpeg 或 webp 工具（
webpmux/dwebp），但非必需。
- 启用 CGO（dev.sh 已默认设置
开发脚本（dev.sh）
- 启动：
./dev.sh start；停止：./dev.sh stop；重启：./dev.sh restart - 状态：
./dev.sh status；日志：./dev.sh logs；仅编译：./dev.sh build - 进程与端口：基于
dev/.env的LISTEN_ADDR自动处理端口占用并强杀冲突进程。
发布（GitHub Actions）
- 生产发布通过 GitHub Actions 完成：
- 推送版本号至
VERSION（并/或创建 Git 标签）→ 触发 release 工作流 - 生成 tar 包：
media-server_<VERSION>_linux_amd64.tar.gz（包含二进制与文档） - 构建并推送 Docker 镜像：
llmnet/media-server:<VERSION>与:latest - 发布前置：自动运行端到端测试（E2E），包含“主机二进制 + MinIO 服务容器”和“Docker 镜像 + MinIO 服务容器”两路验证；任一路失败将阻断发布。
- 推送版本号至
测试（可选）
- 先启动服务并准备 MinIO/S3。
- 运行：
go run ./tests - 覆盖直出/图片/视频/ETag/条件请求等；报告输出至
tests/REPORT.md。
故障排查
- 确认 ffmpeg 已安装并在 PATH 中（
ffmpeg -version）。 - 校验 S3 连接参数（
S3_ENDPOINT/S3_USE_PATH_STYLE等）。 - 查看运行日志：
./dev.sh logs。