Minio on Liangweidong's blog

MinIO 对象存储实战：单节点 / 集群 / 桶复制 / Spring Boot 集成

Thu, 15 Sep 2022 00:00:00 +0800

MinIO 是 S3 兼容的开源对象存储——国内用得最多的"自建 S3"。本篇把单节点部署、4 节点集群搭建、桶复制双向同步、漏洞修复、Spring Boot 集成一次性整理清楚。

阅读对象：需要自建对象存储的后端 / 运维工程师 覆盖范围：MinIO 单节点 / 4 节点集群 / mc 客户端 / 桶复制 / 主主双向同步 / CVE 漏洞修复 / Nginx 反代安全加固 / Spring Boot 集成 / 分片上传 / 断点续传

一、MinIO 简介

MinIO 的核心特点：

S3 兼容：所有 S3 SDK / 工具都能直接对接
高性能：单机读写可达 100+ GB/s
纠删码：默认 EC:4（4 份数据分片可容忍 4 块盘坏）
多语言 SDK：Java / Go / Python / Node.js / .NET
部署简单：单二进制 + 一个目录就能跑

对比：

维度	MinIO	Ceph	SeaweedFS
部署难度	极简	复杂	中等
性能	极高	高	高
集群最少节点	1（4 节点为生产推荐）	3	3
S3 兼容	100%	✅	✅
适用规模	TB ~ 100PB	PB+	TB ~ PB

When to use：

替代 AWS S3、阿里云 OSS 做自托管

存图片 / 视频 / 备份文件 / 日志

大数据 / AI 训练数据湖

二、单节点部署

2.1 拉取镜像

1

docker pull minio/minio:RELEASE.2023-06-09T07-32-12Z.fips

2.2 启动

1
2
3
4
5
6
7
8
9


docker run -d --name minio --restart=always \
 -p 9091:9091 \
 -p 9090:9090 \
 -v /home/docker/data:/data \
 -e "MINIO_ROOT_USER=root" \
 -e "MINIO_ROOT_PASSWORD={{REDACTED}}" \
 -e "MINIO_SERVER_URL=http://internal.example.com:9091" \
 minio/minio:RELEASE.2023-06-09T07-32-12Z.fips \
 server /data --console-address ":9090" --address ":9091"

端口分配：

9091：S3 API（程序用这个）
9090：Web Console（管理用这个）

环境变量：

MINIO_ROOT_USER / MINIO_ROOT_PASSWORD：管理员账号（旧版本是 MINIO_ACCESS_KEY / MINIO_SECRET_KEY）
MINIO_SERVER_URL：S3 API 外部地址——代码里要用这个

2.3 启动后状态

1
2
3


Status: 1 Online, 0 Offline.
S3-API: http://172.17.0.12:9000 http://127.0.0.1:9000
Console: http://172.17.0.12:9090 http://127.0.0.1:9090

进入容器：

1
2


docker exec -it minio bash
# 配置文件：/usr/local/minio/config

三、4 节点集群部署

3.1 集群规划

节点	IP	角色
node1-1	10.0.1.1	机房 1
node1-2	10.0.1.2	机房 1
node2-1	10.0.2.1	机房 2
node2-2	10.0.2.2	机房 2

3.2 /etc/hosts 配置

1
2
3
4
5
6
7


# 4 个节点都执行
cat >> /etc/hosts <<'EOF'
10.0.1.1 node1-1
10.0.1.2 node1-2
10.0.2.1 node2-1
10.0.2.2 node2-2
EOF

3.3 启动集群

1
2
3
4
5
6
7
8
9


docker run -d --restart=always --name minio \
 --net=host \
 -e MINIO_ROOT_USER=root \
 -e MINIO_ROOT_PASSWORD={{REDACTED}} \
 -v /data/minio/data1:/data1 \
 -v /data/minio/data2:/data2 \
 minio/minio:RELEASE.2023-06-09T07-32-12Z.fips \
 server http://node1-{1...2}:9000/data{1...2} http://node2-{1...2}:9000/data{1...2} \
 --console-address ":9090" --address ":9091"

关键参数：

--net=host：集群通信必须 host 网络
4 节点 8 盘：默认 EC:4 编码，可容忍 4 块盘同时损坏
/data1 /data2：每个节点挂 2 块盘
node1-{1...2}：Docker 展开为 node1-1 node1-2

3.4 集群运维

1
2
3
4
5


# 查看集群状态
mc admin info minio-cluster

# 看每个节点磁盘
mc admin info minio-cluster --json | jq '.info.servers[].state'

四、mc 客户端

4.1 安装

1
2
3
4
5
6


# Linux
curl https://dl.min.io/client/mc/release/linux-amd64/mc -o /usr/local/bin/mc
chmod +x /usr/local/bin/mc

# Windows
# 下载 https://dl.min.io/client/mc/release/windows-amd64/mc.exe

4.2 常用命令

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


# 配置 server alias
mc config host add <ALIAS> <S3-ENDPOINT> <ACCESS-KEY> <SECRET-KEY>

# 列出文件
mc ls <ALIAS>/<bucket>

# 创建 bucket
mc mb <ALIAS>/<bucket-name>

# 上传
mc cp <local-path> <ALIAS>/<bucket>/<key>

# 同步
mc mirror <src> <dst>

# 删除
mc rm <ALIAS>/<bucket>/<key> --recursive --force

4.3 完整示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


# 1. 加 alias
mc alias set prod http://minio.internal.example.com:9091 root {{REDACTED}}
mc alias set staging http://minio-staging.internal.example.com:9091 root {{REDACTED}}

# 2. 列出所有 bucket
mc ls prod

# 3. 上传整个目录
mc cp ./uploads/ prod/file/ --recursive

# 4. 同步两个 bucket（增量）
mc mirror prod/file staging/file

# 5. 带版本号恢复
mc cp --rewind "2025-12-12T08:00:00Z" --recursive prod/file/dev/ prod/file/dev/

五、桶复制：跨集群数据同步

5.1 单向复制

1
2
3
4
5
6
7
8
9


# 源集群：minio-prod
# 目标集群：minio-staging

# 在目标集群创建 bucket
mc mb minio-staging/file

# 在源集群加复制规则
mc replicate add minio-prod/file \
 --remote-bucket http://{{REPL_USER}}:{{REPL_PASS}}@minio-staging.internal.example.com:9091/file

注意：

源和目标 MinIO 版本必须一致
桶复制只同步新文件，存量数据用 mc mirror 全量同步

5.2 双向主主复制

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


# 在两个集群都执行

# prod 集群
mc replicate add minio-prod/file \
 --remote-bucket http://{{REPL_USER}}:{{REPL_PASS}}@minio-staging.internal.example.com:9091/file \
 --replicate "delete,delete-marker,existing-objects" \
 --sync

# staging 集群
mc replicate add minio-staging/file \
 --remote-bucket http://{{REPL_USER}}:{{REPL_PASS}}@minio-prod.internal.example.com:9091/file \
 --replicate "delete,delete-marker,existing-objects" \
 --sync

# 启用版本控制
mc version enable minio-prod/file
mc version enable minio-staging/file

效果：

上传到 prod 自动同步到 staging
上传到 staging 自动同步到 prod
删除同步

停机测试：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 1. 停 staging
docker stop minio-staging

# 2. 上传到 prod
mc cp test.txt minio-prod/file/

# 3. 启动 staging
docker start minio-staging

# 4. 等待 sync 自动同步（一般 30 秒内）
mc ls minio-staging/file/

六、漏洞修复：桶路径遍历

6.1 漏洞描述

CVE 严重等级：高。当 MinIO 暴露在公网 + 配置 Access Policy 为 public 时，任何人通过桶路径就能列出所有文件：

1

http://minio.example.com:9091/file/

返回的 XML 包含整个桶的所有文件元信息（文件名 + 大小 + 修改时间）。敏感数据直接泄露。

6.2 漏洞根源

listObjects 默认返回 1000 条
公开 bucket + 公开 URL = 可遍历所有资源

6.3 修复方案

方案 A：Nginx 反代 + 路径屏蔽（最推荐）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


server {
 listen 80;
 server_name minio.example.com;

 # 屏蔽桶路径直接访问
 location ^~ /images {
 rewrite ^/images/(.+)$ /images/$1 break;
 proxy_pass http://minio_local_url/;
 }
 # 其他路径禁止
 location / {
 return 403;
 }
}

效果：

http://minio.example.com/images/bucket/file.txt → ✅ 正常下载
http://minio.example.com/images/bucket/ → ❌ 403 禁止列出

方案 B：Bucket 权限收紧

进入 MinIO Console → Bucket → Access Policy → Custom：

1
2


Prefix: *
Access: Read Only (no List)

这样单个文件还能下载，但桶路径列出被禁止。

方案 C（最佳实践）：

MinIO 不暴露公网：只在内网
Nginx 反代 + 路径重写：唯一对外的入口
Bucket 全部 private：永远不开 public
预签名 URL 访问：临时分享用 mc share 或 SDK 生成

七、Spring Boot 集成

7.1 添加依赖

1
2
3
4
5


<dependency>
 <groupId>io.minio</groupId>
 <artifactId>minio</artifactId>
 <version>8.5.10</version>
</dependency>

7.2 配置文件

1
2
3
4
5


minio:
 endpoint: http://minio.internal.example.com:9091
 access-key: root
 secret-key: {{REDACTED}}
 bucket: file

7.3 Spring Boot 配置类

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


@Configuration
public class MinioConfig {
 @Value("${minio.endpoint}")
 private String endpoint;
 @Value("${minio.access-key}")
 private String accessKey;
 @Value("${minio.secret-key}")
 private String secretKey;

 @Bean
 public MinioClient minioClient() {
 return MinioClient.builder()
 .endpoint(endpoint)
 .credentials(accessKey, secretKey)
 .build();
 }
}

7.4 上传服务

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


@Service
public class MinioService {
 @Autowired
 private MinioClient minioClient;

 public String uploadFile(MultipartFile file, String bucket) throws Exception {
 String objectName = UUID.randomUUID().toString() + "-" + file.getOriginalFilename();

 // 1. 确保 bucket 存在
 boolean found = minioClient.bucketExists(BucketExistsArgs.builder().bucket(bucket).build());
 if (!found) {
 minioClient.makeBucket(MakeBucketArgs.builder().bucket(bucket).build());
 }

 // 2. 上传
 minioClient.putObject(
 PutObjectArgs.builder()
 .bucket(bucket)
 .object(objectName)
 .stream(file.getInputStream(), file.getSize(), -1)
 .contentType(file.getContentType())
 .build()
 );

 return minioClient.getPresignedObjectUrl(
 GetPresignedObjectUrlArgs.builder()
 .bucket(bucket)
 .object(objectName)
 .method(Method.GET)
 .build()
 );
 }
}

八、Spring Boot 高级特性

8.1 分片上传

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


public String initiateMultipartUpload(String bucket, String fileName) throws Exception {
 return minioClient.initiateMultipartUploadAsync(
 InitiateMultipartUploadArgs.builder()
 .bucket(bucket)
 .object(fileName)
 .build()
 ).get().uploadId();
}

public void uploadPart(String bucket, String fileName, String uploadId,
 int partNumber, InputStream data, long size) throws Exception {
 minioClient.uploadPartAsync(
 UploadPartArgs.builder()
 .bucket(bucket)
 .object(fileName)
 .uploadId(uploadId)
 .partNumber(partNumber)
 .stream(data, size, -1)
 .build()
 ).get();
}

8.2 断点续传

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// 1. 客户端检查已上传的分片
ListPartsResponse parts = minioClient.listParts(listPartsArgs);

// 2. 跳过已上传的分片
for (int i = 0; i < parts.result().partList().size(); i++) {
 Part part = parts.result().partList().get(i);
 log.info("已上传分片: {} ({} bytes)", part.partNumber(), part.size());
}

// 3. 接着上传未完成部分

8.3 秒传

1
2
3
4
5
6


public boolean isFileExist(String bucket, String md5) throws Exception {
 Iterable<Result<Item>> results = minioClient.listObjects(
 ListObjectsArgs.builder().bucket(bucket).prefix(md5).build()
 );
 return results.iterator().hasNext();
}

前端流程：

1
2
3
4


1. 计算文件 MD5
2. 调后端接口 "isFileExist(md5)"
3. 如果存在 → 秒传成功（直接返回 URL）
4. 如果不存在 → 走后端生成上传凭证 → 前端直传 MinIO

8.4 文件合并

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


// 前端传完所有分片后调
public void composeFile(String bucket, String targetName, List<String> parts) throws Exception {
 List<ComposeSource> sources = new ArrayList<>();
 for (int i = 0; i < parts.size(); i++) {
 sources.add(ComposeSource.builder()
 .bucket(bucket)
 .object(parts.get(i))
 .build());
 }
 minioClient.composeObject(
 ComposeObjectArgs.builder()
 .bucket(bucket)
 .object(targetName)
 .sources(sources)
 .build()
 );
}

8.5 Nginx 上传调优

1
2
3


# 加大请求体（默认 1m 太小）
client_max_body_size 1024m;
keepalive_timeout 75s;

8.6 Spring Boot 上传调优

1
2
3
4
5


spring:
 servlet:
 multipart:
 max-file-size: 1024MB
 max-request-size: 1024MB

九、监控与运维

9.1 Prometheus metrics

MinIO 默认暴露 /minio/v2/metrics/cluster 端点：

1
2
3
4
5
6


# prometheus.yml
scrape_configs:
 - job_name: 'minio'
 metrics_path: '/minio/v2/metrics/cluster'
 static_configs:
 - targets: ['minio.internal.example.com:9091']

9.2 关键指标

minio_cluster_disk_used_total：磁盘使用
minio_cluster_disk_free_total：剩余空间
minio_s3_requests_total：S3 请求数
minio_s3_requests_errors_total：错误数

9.3 告警规则

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


groups:
- name: minio
 rules:
 - alert: MinIODiskFull
 expr: minio_cluster_disk_free_total / minio_cluster_disk_total < 0.1
 for: 5m
 labels:
 severity: critical
 annotations:
 summary: "MinIO 磁盘使用率超过 90%"

十、典型坑位

10.1 启动报 “no credentials”

修复：

1
2


# 环境变量要用 MINIO_ROOT_USER / MINIO_ROOT_PASSWORD（v4 之后）
# 不是 MINIO_ACCESS_KEY / MINIO_SECRET_KEY

10.2 集群节点无法通信

症状：集群启动后某个节点状态 Offline。

修复：

4 个节点 /etc/hosts 都加完整映射
检查 9000 端口互通：nc -zv node1-2 9000
防火墙放过 9000

10.3 上传文件 0 字节

症状：Java 上传后文件 0 字节。

修复：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 错误写法
minioClient.putObject(bucket, objectName, inputStream);

// 正确写法：必须传 size
minioClient.putObject(
 PutObjectArgs.builder()
 .bucket(bucket)
 .object(objectName)
 .stream(inputStream, inputStream.available(), -1)
 .build()
);

inputStream.available() 在某些流上返回 0，必须手动传 size。

十一、最佳实践清单

MinIO 永远不暴露公网：内网 + Nginx 反代
Bucket 全部 private：用预签名 URL 临时分享
Nginx 路径重写：屏蔽桶路径直接访问
集群至少 4 节点：生产强烈推荐
EC 编码：默认 EC:4，可容忍 4 块盘坏
版本控制必开：防止误删除
桶复制必配：跨机房 / 跨地域容灾
Prometheus 监控：磁盘 / 请求 / 错误率
定期备份：用 mc mirror 备份到 OSS

2024+ 视角补充

本文写于 2022-09，2024-2026 期间 MinIO 关键演进：

MinIO RELEASE.2024-08+：AI 推理优化（GPU 直通 / 大模型权重加载）；Iceberg / Delta Lake 表格式支持（数据湖场景）
MinIO 2024+ 性能：单节点 100+ GB/s（NVMe + 网络优化）；EC 编码 8+2（vs 之前 4+2）—— 更大集群容错
MinIO 2025+：Kubernetes Operator GA——minio/operator 已是生产级（强烈推荐 K8s 部署）
MinIO 许可证变更（2024-01）：AGPL 3.0——之前是 Apache 2.0。这对SaaS 厂商影响大（必须开源），企业内部自用无影响
竞品（2024+ 视角）：
- Ceph Quincy / Reef（2024-2025）：Ceph 18 Reef 性能优化（vs MinIO 优势在多协议——RBD / CephFS / RGW）
- Garage 1.0+（2024-2025）：Rust 写的小型 S3 兼容存储——轻量替代
- SeaweedFS 3.x（2024）：FUSE 挂载 / 极简部署
- Cloudflare R2 / Backblaze B2 / 阿里云 OSS（公有云 S3 兼容）——按量计费无需运维

实战建议（2025-2026 视角）：

企业内部 S3 兼容存储 → MinIO 仍是首选（AGPL 不影响自用）
K8s 部署 → MinIO Operator（K8s Operator 模式）2025+ 是生产级
数据湖 / 大数据 → MinIO + Iceberg / Delta Lake（2024-2025 主流）
公有云 → 直接用 R2 / OSS / S3，避免运维
轻量自托管 → Garage 1.0+（10MB 级别二进制）

下一步

想看 NextCloud 网盘自托管（家用云盘）→ NextCloud 网盘自托管
想看 Seafile 私有云盘（高性能文件同步）→ Seafile 私有云盘
想看 FTP 服务自托管（vsftpd / pure-ftpd）→ FTP 服务自托管
想看 Cloudreve 网盘（多存储后端）→ Cloudreve 网盘
想看 Nginx 自建镜像实战（含反代安全加固）→ Nginx 自建镜像实战

Nginx 反向代理实战：WebSocket、HTTPS、静态站点与 MinIO 网关

Fri, 15 Apr 2022 00:00:00 +0800

Nginx 几乎是后端服务的标配——静态站点、反向代理、负载均衡、WebSocket 网关、HTTPS 终结，每个开发者都用过。但真正"线上跑得稳"需要把几个坑都踩过：WebSocket 反代不写 Upgrade 头、gzip 配错类型反向变慢、HTTPS 证书路径不对、buffer 不够大上传大文件 502。这篇文章把零散在多个笔记里的 Nginx 实战经验整理成一篇。

阅读对象：需要在容器化环境部署 Nginx 做反向代理/静态服务/WebSocket 网关的同学
覆盖范围：Nginx 容器化部署、反向代理基础、HTTPS 终结、WebSocket 反代、gzip/buffer 优化、MinIO 反代示例

一、容器化部署

1.1 最简启动

1

docker run -d --restart=always --name nginx -p 80:80 nginx:stable

推荐用 nginx:stable 而不是 nginx:latest：stable 标签跟小版本号（1.22、1.24 等），latest 偶尔会跳大版本。

1.2 配置持久化

生产环境必须挂载配置和静态文件：

1
2
3
4
5
6
7


docker run -d --name nginx --restart=always -p 80:80 \
 -v /home/nginx/logs:/var/log/nginx \
 -v /home/nginx/conf/conf.d:/etc/nginx/conf.d \
 -v /home/nginx/conf/nginx.conf:/etc/nginx/nginx.conf:ro \
 -v /home/nginx/dist:/usr/share/nginx/html \
 -v /etc/localtime:/etc/localtime:ro \
 nginx:stable

或者 host 网络模式（适合内网用 80 端口）：

1
2
3
4
5
6


docker run -d --name nginx --restart=always --net=host \
 -v /home/docker/nginx/log:/var/log/nginx \
 -v /home/docker/nginx/conf/conf.d:/etc/nginx/conf.d \
 -v /home/docker/nginx/conf/stream:/etc/nginx/stream \
 -v /home/docker/nginx/conf/nginx.conf:/etc/nginx/nginx.conf:ro \
 nginx:stable

1.3 Alpine 版（更小）

1
2
3
4
5
6
7


docker run -d --name nginx --restart=always -p 80:80 \
 -v /home/nginx/logs:/var/log/nginx \
 -v /home/nginx/conf/conf.d:/etc/nginx/conf.d \
 -v /home/nginx/conf/nginx.conf:/etc/nginx/nginx.conf:ro \
 -v /home/nginx/dist:/usr/share/nginx/html \
 -v /etc/localtime:/etc/localtime:ro \
 nginx:1.25-alpine

Alpine 版镜像只有 40MB 左右，但没有预装 shell 和常用工具（wget/curl/vi），排查问题时进容器会比较痛苦。

二、生产级 nginx.conf

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71


user root;
worker_processes 1; # 推荐设为 CPU 核心数

error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;

events {
 worker_connections 1024;
}

http {
 include /etc/nginx/mime.types;
 default_type application/octet-stream;

 log_format main '$remote_addr - $remote_user [$time_local] "$request" '
 '$status $body_bytes_sent "$http_referer" '
 '"$http_user_agent" "$http_x_forwarded_for"';

 access_log /var/log/nginx/access.log main;

 sendfile on;
 keepalive_timeout 65;

 autoindex on;

 # ===== gzip 优化 =====
 gzip on;
 gzip_buffers 32 4K;
 gzip_comp_level 6;
 gzip_min_length 1k;
 gzip_types application/javascript text/css text/xml;
 gzip_disable "MSIE [1-6]\.";
 gzip_http_version 1.1;
 gzip_vary on;

 # ===== 客户端 body/header buffer（上传大文件必须调）=====
 client_body_buffer_size 1024k;
 client_max_body_size 2048m;

 client_header_buffer_size 128k;
 large_client_header_buffers 4 128k;

 # ===== 代理 buffer =====
 proxy_buffer_size 256k;
 proxy_buffering on;
 proxy_buffers 64 128k;
 proxy_busy_buffers_size 512k;

 # ===== FastCGI buffer =====
 fastcgi_buffers 6 512k;
 fastcgi_buffer_size 512k;
 fastcgi_busy_buffers_size 512k;
 fastcgi_temp_file_write_size 512k;
 fastcgi_intercept_errors on;

 # ===== WebSocket 关键配置（http 段顶层）=====
 map $http_upgrade $connection_upgrade {
 default upgrade;
 '' close;
 }

 include /etc/nginx/conf.d/*.conf;
}

# ===== TCP/UDP 4 层转发（可选）=====
stream {
 log_format proxy '[$time_local] $protocol status:$status, bytes client:$bytes_sent/$bytes_received $session_time, '
 'client: $remote_addr, upstream:"$upstream_addr", '
 'bytes upstream:$upstream_bytes_sent $upstream_bytes_received $upstream_connect_time';
 include /etc/nginx/stream/*.conf;
}

关键参数解读：

client_max_body_size 2048m：上传文件超过默认 1M 会 413，调大

client_header_buffer_size 128k：HTTP header 单行超过 1k 会 400，调大

proxy_buffer_size / proxy_buffers：调大避免后端响应一次性写入临时文件

map $http_upgrade $connection_upgrade：WebSocket 反代必须，否则 426 错误

三、HTTPS + 自动跳转

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


server {
 listen 443 ssl;
 server_name example.com;

 ssl_certificate /www/server/panel/vhost/cert/example.com/fullchain.pem;
 ssl_certificate_key /www/server/panel/vhost/cert/example.com/privkey.pem;
 ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;

 charset utf-8;

 location / {
 proxy_pass http://localhost:9000;
 proxy_redirect http:// https://;
 proxy_set_header Host $http_host;
 }
}

server {
 listen 80;
 server_name example.com;

 # HTTP 自动跳 HTTPS
 if ($scheme = http) {
 return 301 https://$host:443$request_uri;
 }
}

证书路径：生产环境用 certbot / acme.sh 自动签发 Let’s Encrypt 证书，定时续期。

四、反向代理 + WebSocket

WebSocket 反代必须带 Upgrade 和 Connection: upgrade 头：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


location ^~ /ws/ {
 proxy_pass http://{{BACKEND_HOST}}/ws/;
 proxy_http_version 1.1;
 proxy_read_timeout 300s;
 proxy_send_timeout 300s;

 proxy_set_header Host $http_host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;

 # WebSocket 关键
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection $connection_upgrade;
}

$connection_upgrade 由前面 map 指令定义，根据客户端 Upgrade 头动态返回 upgrade 或 close。如果忘了配 map，WebSocket 连接会被 nginx 关闭。

五、MinIO 网关示例

MinIO 经常用 Nginx 做反代，重点是 WebSocket（控制台实时通知）+ 大文件上传：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


location ^~ /minio/ {
 proxy_pass http://localhost:9090/;
 proxy_read_timeout 300s;
 proxy_send_timeout 300s;

 proxy_set_header Host $http_host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;
 proxy_http_version 1.1;

 # WebSocket
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection $connection_upgrade;
}

MINIO_BROWSER_REDIRECT_URL 必须配成 Nginx 转发后的地址，否则 MinIO 控制台会 404：

1
2


environment:
 - MINIO_BROWSER_REDIRECT_URL=http://{{NGINX_HOST}}/minio

六、踩坑清单

WebSocket 426/断开——忘了 map $connection_upgrade，或者 location 段漏 Upgrade 头
上传 413——client_max_body_size 默认 1M，调成业务需要的最大值
Header 400——client_header_buffer_size 默认 1k，Cookie 巨长的请求会超
代理慢/卡顿——proxy_buffer_size 太小，后端响应被频繁写入临时文件
gzip 没生效——gzip_types 漏了类型，或者 gzip_min_length 设太大（小文件不压缩）
配置改完没生效——nginx -s reload 失败（语法错），需要 docker logs nginx 查原因
HTTPS 跳不过来——return 301 写在 location / 里而不是 server 顶层
跨域 CORS——后端没设 CORS 头，Nginx 要么 add_header 加，要么在 if 段处理 OPTIONS 预检

七、2024+ 视角补充

本文写于 2022-04，2024-2026 期间 Nginx 关键演进：

Nginx 1.25+（2023-06 起）：HTTP/3 (QUIC) 实验性支持；gRPC 代理原生；动态 SSL 证书加载（不用 reload）
Nginx 1.27 LTS（2024-11）：HTTP/3 默认开；OpenSSL 3.x 兼容；更精细的限流（limit_req_dry_run 等）
Nginx Ingress 1.10+（K8s）：Gateway API 全面支持（vs 老 Ingress API）；IPV6 双栈
Nginx Unit 1.32+：应用服务器模式（跑 Go / Node / Python / Java / PHP / Perl）——Web 服务器 + 应用服务器一体
OpenResty 1.25+：Lua 生态成熟，WAF / API Gateway 场景仍是首选
替代品（2024+ 视角）：
- Caddy 2.x：自动 HTTPS / Caddyfile 简洁 / Go 跨平台——新项目首选
- Traefik 3.x：K8s 原生 / 自动服务发现 / Let’s Encrypt 自动化
- HAProxy 3.0+：四层代理性能优于 Nginx，数据库 / TCP 代理首选
- Envoy 1.32+：Service Mesh 标配（Istio / Consul / Linkerd）

实战建议（2025-2026 视角）：

传统 Web 反代 / 静态站 → Nginx 1.27 LTS 仍是生产首选
K8s 入口 → Nginx Ingress 1.10+ / Traefik 3.x / Gateway API
数据库 / TCP 代理 → HAProxy 3.0+（性能与功能强于 Nginx stream）
新项目想要最少配置 → Caddy 2.x（HTTPS 配置从 30 行降到 3 行）

八、参考资料

Nginx 官方文档：http://nginx.org/en/docs/
Nginx 反向代理 WebSocket：https://nginx.org/en/docs/http/websocket.html
Mozilla SSL 配置生成器：https://ssl-config.mozilla.org/

下一步

想做安全网关？→ Vaultwarden 自托管密码一文（也用 Nginx 反代）
想做企业 VPN？→ OpenVPN 自建 VPN 服务一文
想用 K8s Ingress？→ 看 K8s 集群流量入口 Ingress-nginx 一文

MinIO / JuiceFS / OpenEBS：K8s 对象存储与本地 PV 全方案

Tue, 15 Aug 2017 00:00:00 +0800

三种 K8s 存储的"非主流"路线

主流 K8s 存储是 NFS + Ceph，但有些场景它们都力不从心：

S3 兼容对象存储（备份、日志、镜像）→ MinIO
海量小文件 + 多云（AI 训练、媒资）→ JuiceFS
本地磁盘池化（DB 性能、StatefulSet）→ OpenEBS

本文一次讲清这三套方案。

适用版本：MinIO 2024.x / JuiceFS 1.x / OpenEBS 3.4

1. MinIO 作为 PV 存储

1.1 思路

通过 k8s-csi-s3 这个 CSI 驱动，让 S3（MinIO）作为 K8s 的 PV 后端——申请 PVC 时自动创建 S3 bucket，Pod 内能像本地目录一样访问。

警告：源码明确写"不建议生产环境使用"。原因是 S3 不是真正的文件系统，POSIX 兼容有限（特别是 append 写）。但作为 静态资源 / 备份 场景的 PV 非常合适。

1.2 要求

Kubernetes 1.16+（CSI v1.0.0）
kubelet 允许特权容器
Docker daemon MountFlags=shared（新增分区无需重启 Docker）

1
2
3
4
5
6


# /etc/systemd/system/docker.service
[Service]
MountFlags=shared
Type=notify
ExecStart=/usr/local/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock
...

1.3 创建 Secret

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


apiVersion: v1
kind: Secret
metadata:
 name: csi-driver-s3-secret
 namespace: kube-system
stringData:
 accessKeyID: "{{MINIO_ACCESS_KEY}}"
 secretAccessKey: "{{MINIO_SECRET_KEY}}"
 endpoint: https://<minio-endpoint>
 region: ""

实际访问密钥用占位符 {{MINIO_ACCESS_KEY}} {{MINIO_SECRET_KEY}} 替代。

1.4 安装 CSI 驱动

按 yandex-cloud/k8s-csi-s3 仓库的 provisioner.yaml / attacher.yaml / csi-driver-s3.yaml / psp.yaml 部署。

1.5 mounter 选择

驱动支持 4 种 mount 工具：

mounter	兼容性	性能	适用
rclone	几乎完全 POSIX	中	通用
s3fs	较大子集	中	通用，不支持 append
goofys	弱	最高	只读/大批量，不支持 append
s3backer	实验性	-	块设备，但卷损坏风险大

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
 name: csi-driver-s3
provisioner: s3.csi.metal-stack.io
parameters:
 mounter: s3fs
 csi.storage.k8s.io/provisioner-secret-name: csi-driver-s3-secret
 csi.storage.k8s.io/provisioner-secret-namespace: kube-system
 csi.storage.k8s.io/controller-publish-secret-name: csi-driver-s3-secret
 csi.storage.k8s.io/controller-publish-secret-namespace: kube-system
 csi.storage.k8s.io/node-stage-secret-name: csi-driver-s3-secret
 csi.storage.k8s.io/node-stage-secret-namespace: kube-system
 csi.storage.k8s.io/node-publish-secret-name: csi-driver-s3-secret
 csi.storage.k8s.io/node-publish-secret-namespace: kube-system

1.6 使用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


apiVersion: v1
kind: PersistentVolumeClaim
metadata:
 name: csi-s3-pvc
 namespace: default
spec:
 accessModes:
 - ReadWriteOnce
 resources:
 requests:
 storage: 1Gi
 storageClassName: csi-s3
---
apiVersion: v1
kind: Pod
metadata:
 name: csi-s3-test-nginx
spec:
 containers:
 - name: csi-s3-test-nginx
 image: nginx
 volumeMounts:
 - mountPath: /var/lib/www/html
 name: webroot
 volumes:
 - name: webroot
 persistentVolumeClaim:
 claimName: csi-s3-pvc
 readOnly: false

1
2
3
4
5


kubectl exec -it csi-s3-test-nginx -- bash
cd /var/lib/www/html/
touch 2024-12-15.txt
ls
# 2024-12-15.txt

MinIO 上能看到自动创建的 bucket 里有这个文件。

2. JuiceFS 架构

2.1 三大组件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


┌─────────────────────────────────────────────────────────┐
│ JuiceFS 文件系统 │
│ │
│ ┌────────────┐ ┌────────────┐ ┌──────────────────┐ │
│ │ JuiceFS │ │ 数据存储 │ │ 元数据引擎 │ │
│ │ Client │ │ (对象存储) │ │ (Redis/TiKV/MySQL│ │
│ │ (FUSE) │ │ S3/MinIO │ │ /PostgreSQL/ │ │
│ │ │ │ Ceph/OSS │ │ SQLite) │ │
│ └─────┬──────┘ └─────┬──────┘ └────────┬─────────┘ │
│ │ │ │ │
│ └───────────────┴──────────────────┘ │
│ POSIX 兼容挂载 │
└─────────────────────────────────────────────────────────┘

Client：所有文件读写都在客户端，通过 FUSE 暴露 POSIX 接口
数据存储：文件切分上传到 S3/MinIO/Ceph
元数据引擎：文件名、权限、目录树、文件锁、引用计数等

2.2 5 种接入方式

方式	适用场景
FUSE	通用，Linux 服务器当本地盘用
Hadoop Java SDK	替代 HDFS
Kubernetes CSI	K8s 集群直接挂载
S3 网关	用 AWS CLI / s3cmd 访问 JuiceFS
WebDAV	HTTP 协议

2.3 K8s 部署

JuiceFS 官方 CSI 文档：https://juicefs.com/docs/zh/community/getting-started/for_distributed

1
2


helm repo add juicefs https://juicedata.github.io/charts
helm install juicefs juicefs/juicefs-csi-driver -n juicefs --create-namespace

创建 Secret 提供元数据引擎与对象存储凭据：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


apiVersion: v1
kind: Secret
metadata:
 name: juicefs-secret
type: Opaque
stringData:
 name: <filesystem-name>
 metaurl: redis://:<redis-password>@<redis-host>:6379/1
 bucket: http://<minio-host>:9000/<bucket>
 access-key: {{MINIO_ACCESS_KEY}}
 secret-key: {{MINIO_SECRET_KEY}}
 storage-class: STANDARD

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
 name: juicefs
provisioner: csi.juicefs.com
parameters:
 csi.storage.k8s.io/provisioner-secret-name: juicefs-secret
 csi.storage.k8s.io/provisioner-secret-namespace: default
 csi.storage.k8s.io/node-publish-secret-name: juicefs-secret
 csi.storage.k8s.io/node-publish-secret-namespace: default
reclaimPolicy: Retain

2.4 适用场景

AI 训练数据集（海量小文件 + POSIX）
媒资管理（图片、视频）
跨云数据共享

3. OpenEBS 本地 PV

3.1 简介

传统 K8s LocalPV 受限于"单节点单盘"，OpenEBS 通过 iSCSI 协议把"工作节点本地盘"池化：

本地卷（LocalPV）：单节点本地盘，性能最高，DB 推荐
复制卷（cStor）：跨节点复制，有冗余（3 副本）

3.2 内核要求

OpenEBS 走 iSCSI，所有节点装客户端：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# CentOS
yum install iscsi-initiator-utils -y

# Ubuntu
apt install -y open-iscsi

# 启动
systemctl enable --now iscsid
systemctl start iscsid.service

# 可选：开启 nvme_tcp
modprobe iscsi_tcp
echo iscsi_tcp >/etc/modules-load.d/iscsi-tcp.conf
echo "nvme_tcp" | sudo tee /etc/modules-load.d/openebs.conf

3.3 部署 Operator

1
2
3
4
5
6
7
8


# OpenEBS 官方源
helm repo add openebs https://openebs.github.io/openebs
helm repo update

helm install openebs \
 --namespace openebs \
 openebs/openebs \
 --create-namespace

或者 yaml 方式：

1

kubectl apply -f https://openebs.github.io/charts/openebs-operator.yaml

3.4 默认存储路径

1
2


- name: BasePath
 value: "/var/openebs/local/"

OpenEBS 在每个节点上 /var/openebs/local/ 下创建 PV。

3.5 使用

OpenEBS 装好后自动创建几个 StorageClass：

1
2
3
4
5


kubectl get sc
# openebs-hostpath 默认
# openebs-device
# openebs-jiva-csi-default
# openebs-zfspv

直接引用：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


apiVersion: v1
kind: PersistentVolumeClaim
metadata:
 name: my-pvc
spec:
 storageClassName: openebs-hostpath
 accessModes:
 - ReadWriteOnce
 resources:
 requests:
 storage: 5Gi

3.6 备份

OpenEBS 推荐用 Velero 做备份，原理是 K8s 资源 + PV 数据快照到对象存储。

1
2
3
4
5
6


velero install \
 --provider aws \
 --bucket <bucket-name> \
 --secret-file ./credentials-velero \
 --backup-location-config region=minio \
 --use-restic

4. 三种方案对比

方案	类型	性能	容量上限	多 Pod 共享	适用
MinIO CSI	对象	中（小文件慢）	无限	否（RWO）	静态资源、备份
JuiceFS	分布式文件	中-高	无限	是（RWX）	AI 数据、媒资
OpenEBS LocalPV	本地盘	最高	单机	否	DB、StatefulSet
OpenEBS cStor	分布式块	中	中	否	通用数据库

5. 排错速查

5.1 MinIO CSI Pod 一直 Pending

通常是 RBAC / ServiceAccount 权限问题：

1
2


kubectl describe pod csi-provisioner-s3 -n kube-system
# 查 Events

5.2 JuiceFS 挂载失败

元数据引擎（Redis/MySQL）网络可达？
对象存储 endpoint 正确？
Secret 里的 access-key / secret-key 权限够？

5.3 OpenEBS Node Disk Manager 没起来

1
2


kubectl get pods -n openebs
# openebs-ndm DaemonSet 没起 = iscsi 没装

5.4 OpenEBS PVC 一直 Pending

1
2
3


kubectl describe pvc my-pvc
# 找"没有可用节点满足 volume node affinity"
# 解决：调度到打了 openebs.io/localpv 标签的节点

6. 小结

K8s 存储选型不是"一刀切"：

MinIO CSI 解决"对象存储当 PV 用"的备份场景
JuiceFS 是"国内开源 + 兼容 S3 + POSIX"的分布式文件
OpenEBS 把"工作节点本地盘"统一管理，性能和 Ceph RBD 不相上下

下一步：K8s PVC 备份恢复：CSI Snapshot / Velero / rsync 三方案。

Windows 自托管服务实战：Nginx、Caddy、Redis、MinIO、Elasticsearch 与 WinSW 注册服务

Thu, 15 Jun 2017 00:00:00 +0800

一、为什么要在 Windows 上自托管服务

Linux 是服务器的主流，但以下场景 Windows 是更好的选择：

本机开发调试：不想用 Docker 跑 Redis / MinIO，直接在 Windows 起一个更轻；
边缘设备：工控机、收银终端、POS 机多数是 Windows；
客户现场：客户系统是 Windows Server，部署要符合现场环境；
个人 NAS / 家用服务器：Windows 桌面系统易用，存储/相册/笔记都靠它。

本文给出 Nginx / Caddy / Redis / MinIO / Elasticsearch 五个常用自托管服务的 Windows 绿色版部署方案，统一用 WinSW 把 exe 注册成系统服务，重启自启。

二、Nginx for Windows

2.1 下载与目录

nginx.org/en/download.html 下载 nginx-1.24.0.zip（mainline 1.25.x 也可以）。

1
2
3
4
5
6
7


D:\portable\dev\nginx-1.24.0\
├── conf\
│ ├── nginx.conf
│ └── conf.d\ # 自定义配置
├── html\
├── logs\
└── nginx.exe

2.2 配置环境变量

1

PATH=D:\portable\dev\nginx-1.24.0

1
2


nginx -v
# nginx version: nginx/1.24.0

2.3 启停命令

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 启动（前台）
start nginx

# 优雅停止
nginx -s stop
nginx -s quit
nginx -s reload # 重载配置（不中断连接）
nginx -s reopen # 重开日志文件

# 暴力杀进程（兜底）
taskkill /f /t /im nginx.exe

2.4 反代示例

conf/conf.d/frontend.conf：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


server {
 listen 8080;
 server_name localhost;

 # 静态站点
 root D:/wwwroot/site;
 index index.html;

 # 反向代理
 location /api/ {
 proxy_pass http://127.0.0.1:3000/;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;
 }

 # WebSocket
 location /ws/ {
 proxy_pass http://127.0.0.1:3001/;
 proxy_http_version 1.1;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection "upgrade";
 }

 # 大文件上传
 client_max_body_size 100m;
}

主 conf/nginx.conf 引入：

1
2
3
4
5
6
7
8


http {
 include mime.types;
 default_type application/octet-stream;
 sendfile on;
 keepalive_timeout 65;
 gzip on;
 include conf.d/*.conf;
}

2.5 TCP/UDP 四层代理

conf/stream/video.conf：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


stream {
 server {
 listen 1935;
 proxy_pass stream_backend;
 }
 upstream stream_backend {
 server 127.0.0.1:1936;
 server 127.0.0.1:1937;
 }
}

启动时 nginx 会要求主 nginx.conf 引入 stream 块，默认 nginx.conf 不带，要手动加。

三、Caddy：自动 HTTPS 的 HTTP/2 服务器

3.1 下载

caddyserver/caddy/releases 下载 caddy_2.6.4_windows_amd64.zip，解压到 D:\portable\dev\caddy。

3.2 Caddyfile 最小配置

1
2
3
4
5
6


example.com {
 root * D:/wwwroot/site
 file_server
 encode gzip
 reverse_proxy /api/* 127.0.0.1:3000
}

3.3 关键命令

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 启动（前台，监视配置改动自动 reload）
.\caddy.exe run --watch

# 启动（守护进程）
.\caddy.exe start

# 格式化配置文件（推荐编辑后立即 fmt）
.\caddy.exe fmt --overwrite Caddyfile

# 自签证书测试
curl https://localhost --ssl-no-revoke

3.4 Caddy vs Nginx

维度	Caddy	Nginx
自动 HTTPS	默认开（Let’s Encrypt）	需 acme.sh + cron
配置语法	极简	模块化、灵活
性能	单核略低于 Nginx	极致优化
生态	较新，模块少	老牌，几乎所有场景都有现成配置
适合	个人/小团队博客、内网工具	生产大流量反代、网关

四、Redis for Windows

4.1 下载

官方 Redis 不提供 Windows 版。社区维护两个分支：

tporadowski/redis（Cygwin 版）；
redis-windows/redis-windows（MinGW 版，2023+ 维护）。

下载 Redis-7.4.1-Windows-x64-cygwin-with-Service.zip，解压到 D:\portable\dev\redis。

4.2 启动

1
2
3
4
5
6
7


# 启动 redis-server
D:\portable\dev\redis\redis-server.exe redis.conf

# 客户端
D:\portable\dev\redis\redis-cli.exe
127.0.0.1:6379> ping
PONG

4.3 配置 redis.conf 关键项

1
2
3
4
5
6
7
8
9


bind 127.0.0.1
port 6379
daemonize no # Windows 不支持 daemonize
loglevel notice
logfile "D:/portable/dev/redis/logs/redis.log"
dir D:/portable/dev/redis/data
maxmemory 256mb
maxmemory-policy allkeys-lru
requirepass {{REDACTED}}

4.4 用 Redis Desktop Manager 连

RDM（uglide/RedisDesktopManager）2021.3 起开源。Windows 端推荐用 Another Redis Desktop Manager，绿色解压即用。

1
2
3


host: 127.0.0.1
port: 6379
password: <requirepass>

五、MinIO：对象存储

5.1 下载

dl.minio.io + dl.min.io/client/mc/release/windows-amd64/mc.exe，放到 D:\portable\dev\minio\。

5.2 目录

1
2
3
4


D:\portable\dev\minio\
├── data\ # 对象数据
├── minio.exe
└── minio.bat # 启动脚本

minio.bat：

1
2
3
4
5


@echo off
set path=D:\portable\dev\minio
set minPath=D:\portable\dev\minio\data
"%path%\minio.exe" server %minPath% --console-address ":9000" --address ":9090"
pause

5.3 启动

1
2
3
4
5


.\minio.bat
# 输出：
# API: http://127.0.0.1:9090
# WebUI: http://127.0.0.1:9000
# 默认账号: minioadmin / minioadmin ← 首次启动后立即改密

5.4 mc 客户端

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# 配置 host
.\mc.exe config host add local http://127.0.0.1:9090 minioadmin minioadmin

# 列 bucket
.\mc.exe ls local/

# 创建 bucket
.\mc.exe mb local/test-bucket

# 上传文件
.\mc.exe cp D:/test.zip local/test-bucket/

# 列已配 host
.\mc.exe config host list

安全提示：minioadmin/minioadmin 是默认账号，生产环境必须通过 MINIO_ROOT_USER / MINIO_ROOT_PASSWORD 环境变量或 config.json 修改。

六、Elasticsearch

6.1 下载

elastic.co/downloads/past-releases#elasticsearch 选 8.x zip。

6.2 启动

1
2


cd D:\portable\dev\elasticsearch-8.11.0
bin\elasticsearch.bat

6.3 关键配置

config/elasticsearch.yml：

1
2
3
4
5
6


cluster.name: dev-cluster
node.name: dev-node-1
network.host: 127.0.0.1
http.port: 9200
discovery.type: single-node
xpack.security.enabled: false

config/jvm.options：

1
2


-Xms2g
-Xmx2g

避坑：Windows 上 ES 跑 2GB 堆需要至少 4GB 物理内存，老机器慎用。

6.4 Kibana 配套

KIMB elastic.co/downloads/kibana 下 Windows zip，启动后访问 http://127.0.0.1:5601，Dev Tools Console 是排查 ES 最方便的工具。

七、WinSW：把 exe 注册成系统服务

7.1 简介

winsw/winsw 是 Windows Service Wrapper，可以把任何可执行文件注册成 Windows 系统服务（支持开机自启、失败重启、日志轮转）。

下载 WinSW-x64.exe（注意 64/32 位），改名成与 XML 同名。

7.2 XML 配置

把 WinSW-x64.exe 复制到 D:\portable\dev\nginx-1.24.0\nginx-service.exe，新建 nginx-service.xml：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


<service>
 <id>nginx-server</id>
 <name>nginx-server</name>
 <description>Nginx 1.24 反向代理服务</description>
 <executable>D:\portable\dev\nginx-1.24.0\nginx.exe</executable>
 <startarguments>-p D:\portable\dev\nginx-1.24.0\</startarguments>
 <stopexecutable>D:\portable\dev\nginx-1.24.0\nginx.exe</stopexecutable>
 <stoparguments>-p D:\portable\dev\nginx-1.24.0\ -s stop</stoparguments>
 <logpath>%BASE%\logs</logpath>
 <log mode="rotate">
 <sizeThreshold>10240</sizeThreshold>
 <keepFiles>3</keepFiles>
 </log>
</service>

7.3 安装 / 启动 / 卸载

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# 安装服务（管理员 cmd）
nginx-service.exe install

# 启动
nginx-service.exe start
nginx-service.exe stop
nginx-service.exe restart
nginx-service.exe status

# 卸载
nginx-service.exe uninstall

# 不重装刷新配置
nginx-service.exe refresh

7.4 日志按时间轮转

1
2
3
4
5
6


<log mode="roll-by-size-time">
 <sizeThreshold>10240</sizeThreshold>
 <pattern>yyyyMMdd</pattern>
 <autoRollAtTime>00:00:00</autoRollAtTime>
 <zipOlderThanNumDays>5</zipOlderThanNumDays>
</log>

7.5 实战：MinIO 服务化

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


<service>
 <id>minio-server</id>
 <name>minio-server</name>
 <description>MinIO 对象存储服务</description>
 <env name="HOME" value="%BASE%"/>
 <env name="MINIO_ROOT_USER" value="root"/>
 <env name="MINIO_ROOT_PASSWORD" value="{{REDACTED}}"/>
 <executable>%BASE%\minio.exe</executable>
 <arguments>server "%BASE%\data" --console-address ":9090" --address ":9091"</arguments>
 <logpath>%BASE%\logs</logpath>
 <log mode="roll-by-size-time">
 <sizeThreshold>10240</sizeThreshold>
 <pattern>yyyyMMdd</pattern>
 </log>
</service>

7.6 WinSW 完整命令表

命令	用途
install	安装服务
uninstall	卸载服务
start	启动
stop	停止
restart	重启
status	查看状态
refresh	刷新服务属性（不重装）
customize	自定义包装可执行文件
dev ps	显示服务进程树
dev kill	强制杀掉服务进程
dev list	列出本 exe 注册的所有服务

八、把它们装在一起的服务清单

1
2
3
4
5
6
7
8


D:\portable\services\
├── nginx\ # 端口 80 / 8080
├── caddy\ # 端口 443（自动 HTTPS）
├── redis\ # 端口 6379
├── minio\ # 端口 9090 (API) / 9000 (WebUI)
├── elasticsearch\ # 端口 9200
├── kibana\ # 端口 5601
└── nssm\ # 备用服务化工具

每个目录下放 <服务名>.exe（WinSW 改名）和 <服务名>.xml，统一 install 即可。

九、常见坑与对策

现象	原因	对策
Nginx 启动 403 Forbidden	SELinux / 文件权限	Windows 上多数是路径写错
Caddy 启动报 “bind: address already in use”	端口被占	`netstat -ano
Redis 启动报 “Bad file format”	Windows redis 版本错	装 Cygwin 版（tporadowski）
MinIO 控制台打不开	防火墙	首次启动后改 `minioadmin` 密码
ES 启动 OOM	JVM 堆	`-Xms1g -Xmx1g` 调小
WinSW 服务起不来	不是管理员	用管理员 cmd

十、下一步

Caddy 进阶：用 Cloudflare DNS plugin 自动签通配符证书
MinIO 进阶：搭建 4 节点分布式集群（参考 2022-09-15《MinIO 对象存储实战》）
Redis 进阶：Redis Sentinel 高可用、Redis Cluster 集群
ES 进阶：用 Docker Compose 拉起 ES + Kibana 全套（参考 2025-03-15《Prometheus 监控告警体系》）