3分钟上手Stash容器化部署：从单节点到弹性扩展全攻略
项目地址: https://gitcode.com/gh_mirrors/st/stash 你是否还在为媒体库管理工具的部署流程繁琐而烦恼？是否担心随着收藏量增长，单服务器性能不足导致卡顿？本文将带你通过Docker Compose实现Stash的一键部署，并详解如何平滑扩展至Docker Swarm集群，让你的媒体管理系统兼具稳定性与弹性。
读完本文你将掌握：
- 3步完成Stash容器化部署
- 自动备份与数据持久化方案
- 基于Docker Swarm的服务弹性扩展
- 多节点负载均衡配置
- 常见问题排查与性能优化
部署环境准备
在开始部署前，请确保你的服务器满足以下条件：
- Docker Engine 20.10+
- Docker Compose v2+
- 至少2GB内存（推荐4GB+）
- 50GB以上可用存储空间
项目已为Docker部署提供完整支持，相关配置文件位于：
单节点快速部署
1. 获取配置文件
首先克隆项目仓库并进入生产配置目录：
git clone https://gitcode.com/gh_mirrors/st/stash.git
cd stash/docker/production
2. 配置自定义参数
编辑docker-compose.yml文件，根据你的需求修改以下关键参数：
version: '3.8'
services:
stash:
image: stashapp/stash:latest
ports:
- "9999:9999" # Web界面端口
volumes:
- ./data:/data # 数据持久化目录
- ./media:/media # 媒体文件目录
environment:
- STASH_STASHDB_URI=http://stashdb:9998 # 元数据库连接
- STASH_LOG_LEVEL=info # 日志级别
restart: unless-stopped
3. 启动服务
执行以下命令启动服务：
docker-compose up -d
服务启动后，访问http://服务器IP:9999即可打开Stash管理界面。首次登录需创建管理员账户并完成初始配置向导。
数据安全与持久化
为防止数据丢失，建议配置定期备份。项目提供了多种数据管理工具：
自动备份配置
在docker-compose.yml中添加备份服务：
services:
# ... 其他服务配置 ...
backup:
image: alpine:latest
volumes:
- ./data:/source
- ./backups:/backups
command: sh -c "tar -czf /backups/stash_$$(date +%Y%m%d).tar.gz /source"
depends_on:
- stash
配合crontab设置每日自动执行：
echo "0 3 * * * cd /path/to/stash/docker/production && docker-compose run --rm backup" | crontab -
Docker Swarm集群扩展
当单节点性能不足时，可通过Docker Swarm实现服务扩展。项目结构中与集群部署相关的模块包括：
初始化Swarm集群
在管理节点执行：
docker swarm init --advertise-addr 你的服务器IP
按照输出提示将其他节点加入集群。
部署Stack文件
创建stash-stack.yml，添加Swarm特定配置：
version: '3.8'
services:
stash:
image: stashapp/stash:latest
ports:
- "9999:9999"
volumes:
- stash-data:/data
- /media:/media # 使用本地媒体目录
environment:
- STASH_STASHDB_URI=http://stashdb:9998
- STASH_MODE=cluster
deploy:
replicas: 3 # 初始副本数
resources:
limits:
cpus: '1'
memory: 2G
restart_policy:
condition: on-failure
placement:
constraints: [node.role == worker]
volumes:
stash-data:
driver: local
部署Stack：
docker stack deploy -c stash-stack.yml stash
服务弹性伸缩
根据负载自动调整服务副本数：
# 扩展至5个副本
docker service scale stash_stash=5
# 缩减至2个副本
docker service scale stash_stash=2
多节点负载均衡
为确保服务高可用，建议配置外部负载均衡器。可使用Traefik或Nginx作为入口流量分发点，项目提供的API模块[internal/api/]支持健康检查和会话保持。
Nginx配置示例
upstream stash_cluster {
server 192.168.1.10:9999;
server 192.168.1.11:9999;
server 192.168.1.12:9999;
ip_hash; # 会话保持
}
server {
listen 80;
server_name media.yourdomain.com;
location / {
proxy_pass http://stash_cluster;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
性能优化与监控
资源限制与调优
根据媒体文件数量和访问量调整资源分配：
服务监控
添加Prometheus和Grafana监控容器健康状态：
services:
prometheus:
image: prom/prometheus
volumes:
- ./prometheus.yml:/etc/prometheus/prometheus.yml
command:
- '--config.file=/etc/prometheus/prometheus.yml'
ports:
- "9090:9090"
grafana:
image: grafana/grafana
volumes:
- grafana-data:/var/lib/grafana
ports:
- "3000:3000"
depends_on:
- prometheus
常见问题排查
服务启动失败
查看容器日志定位问题：
docker logs -f stash_stash_1
常见原因及解决：
- 端口冲突：修改
docker-compose.yml中的端口映射 - 权限问题：确保数据目录权限为775
- 资源不足：增加服务器内存或调整服务资源限制
媒体文件无法访问
检查卷挂载配置，确保媒体目录正确映射：
# 检查卷挂载状态
docker volume inspect stash_data
性能优化建议
- 使用SSD存储元数据库
- 对大型媒体文件启用分片处理stream_segmented.go
- 配置适当的缓存大小cache.go
- 定期清理临时文件clean.go
总结与展望
通过本文介绍的Docker Compose和Docker Swarm部署方案，你已掌握Stash从单节点到集群的完整部署流程。项目持续开发中，未来将支持更多高级特性：
- Kubernetes部署支持
- 自动扩缩容策略
- 跨区域数据同步
- GPU硬件加速转码
建议定期关注项目更新：
希望本文对你的Stash部署有所帮助！如有任何问题，欢迎在项目Issue中提出或参与社区讨论。别忘了点赞收藏，以便日后查阅。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
