mikochi 1.12.2 Docker Compose 部署指南
mikochi 1.12.2 Docker Compose 部署实战：栈编排文件（显式项目名/子网/端口）、首次启动登录认证（JWT 与限流实测）、目录浏览与 multipart 上传验证、数据持久化、环境变量表与重启后令牌失效等常见问题，全部命令含真实回显。
mikochi 1.12.2 Docker Compose 部署指南
目标：本篇在 Linux 服务器上以 Docker Compose 从零部署 mikochi 1.12.2 自托管文件浏览器，覆盖栈编排文件、首次启动登录认证、目录浏览与文件上传的实测验证及常见问题，全流程已在真实环境实测通过。
一、环境信息
- 操作系统：Linux x86_64（内核 5.x 系列，Ubuntu 系发行版实测）
- Docker：29.9.2（build a82e528）
- Docker Compose：v5.6.1（v2 语法兼容）
- mikochi：1.12.2（官方镜像
zer0tonin/mikochi:1.12.2，压缩体积 209MB，digestsha256:65ee9bf2f5315cef6a8caafa6bf9528bf998807be8a9872a38bf3627dbb4791c） - 服务端口：宿主机 8148 → 服务内部 8080（8148 为本机空闲端口，部署前需按实际情况确认）
- 专用网络：
mikochi-1.12.2-net（显式子网10.89.56.0/24） - 数据目录：
/opt/data/quzuo/tmp/mikochi/data（宿主机）→/data（服务内，即DATA_DIR） - 登录凭据：
admin/q1w2e3r4（本文演示账号，生产环境请替换为强密码） - 版本发布时间：1.12.2 于 2026-10-15 发布（查询日期 2026-10-30）
二、镜像选型说明
mikochi 官方在 Docker Hub 发布镜像 zer0tonin/mikochi，同一 tag 提供多架构清单（amd64 / arm64 / armv7），官方 README 的部署示例即为该镜像，无需第三方转存。
- tag 选型：生产环境固定具体版本 tag（如
1.12.2）而非latest，便于回滚与审计。mikochi 的版本 tag 不带v前缀，与 GitHub Release tag 一致。 - 镜像构成：单进程交付——Gin 服务同时承载 REST API 与前端静态文件（Preact SPA），无附属组件，无需数据库。
- 升级路径：更新 tag 号后
docker compose up -d重建即可；数据全部在外部挂载目录中，重建不丢数据（注意一个重启行为差异，见"十、常见问题"第 1 条）。
三、前置条件
- 已安装 Docker 与 Docker Compose v2+，且当前用户在 docker 用户组（或具备等效权限）；
- 宿主机 8148 端口空闲（自检命令：
ss -ltn | grep 8148，无输出即空闲）； - 规划好被浏览的数据目录（本文以
/opt/data/quzuo/tmp/mikochi/data为例），mikochi 对该目录拥有读写权限； - 若使用专用网络，选定一个未被占用的子网槽位（本文取
10.89.56.0/24，可用docker network inspect逐一核对已占网段）。
端口与网段占用自检：
ss -ltn | grep -E ':(8148)\b'
docker network ls -q | xargs -r docker network inspect --format '{{.Name}} {{range .IPAM.Config}}{{.Subnet}}{{end}}' | grep 10.89.56
两条命令均无输出，说明端口与子网均可用。
四、部署步骤
4.1 编排文件
在工作目录创建 docker-compose.yml（本文落盘于 /opt/data/quzuo/tmp/mikochi/），必须显式声明项目名 name: mikochi-1.12.2-stack，避免多套部署共存时项目同名互相覆盖：
name: mikochi-1.12.2-stack
services:
web:
image: zer0tonin/mikochi:1.12.2
container_name: mikochi-1.12.2-web
ports:
- "8148:8080"
environment:
DATA_DIR: "/data"
USERNAME: "admin"
PASSWORD: "q1w2e3r4"
volumes:
- /opt/data/quzuo/tmp/mikochi/data:/data
networks:
- mikochi-net
restart: unless-stopped
networks:
mikochi-net:
name: mikochi-1.12.2-net
driver: bridge
ipam:
config:
- subnet: 10.89.56.0/24
配置要点：
container_name：按<产品>-<版本>-<用途>规范命名为mikochi-1.12.2-web；ports：宿主机 8148 映射服务内 8080（mikochi 固定监听HOST默认值0.0.0.0:8080）；environment：DATA_DIR指定被浏览的根目录，USERNAME/PASSWORD为登录凭据（源码默认值为root/pass，必须显式覆盖）；networks：显式命名网络并固定子网，防止与其他服务的动态网段冲突。
4.2 拉起服务
docker compose up -d
实测回显（逐行照抄）：
Network mikochi-1.12.2-net Creating
Network mikochi-1.12.2-net Created
Container mikochi-1.12.2-web Creating
Container mikochi-1.12.2-web Created
Container mikochi-1.12.2-web Starting
Container mikochi-1.12.2-web Started
4.3 状态确认
docker ps --filter name=mikochi --format '{{.Names}} | {{.Status}} | {{.Ports}}'
docker inspect mikochi-1.12.2-web --format '{{range .NetworkSettings.Networks}}{{.IPAddress}} {{.Gateway}}{{end}}'
实测回显：
mikochi-1.12.2-web | Up 3 seconds | 0.0.0.0:8148->8080/tcp, [::]:8148->8080/tcp
10.89.56.2 10.89.56.1
服务已在 8148 端口监听，专用网络内分配到 10.89.56.2。
五、首次启动认证
浏览器访问 http://<服务器IP>:8148，进入 mikochi 的登录页（Preact 单页应用，服务端首页响应实测为 489 字节的 <!doctype html> 文档，静态资源加载后渲染登录表单）。输入编排在 environment 中的用户名 admin 与密码 q1w2e3r4 完成登录，即可进入文件浏览界面。
登录动作对应 REST API 的 POST /api/login（前端表单底层即此接口），可用 curl 验证认证链路：
curl -s -X POST http://127.0.0.1:8148/api/login \
-H 'Content-Type: application/json' \
-d '{"username":"admin","password":"q1w2e3r4"}'
实测回显（token 为 JWT，节选）：
{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6Im1pa29jaGktdXNlciIsImlzcyI6Ik1pa29jaGkiLCJleHAiOjE3OTU5NzUwNjksImlhdCI6MTc5MzM0NzA2OSwianRpIjoiNDk5OTM5MTEtODY3Yy00NDVlLWJhOGEtMGZiZDk1YjVhMTljIn0.d0tN0jDdvqgDYdWeaq8ePUhwc8Dm-rfQvXsjHLMD52Y"}
错误凭据与爆破防护的实测对照：
curl -s -X POST http://127.0.0.1:8148/api/login \
-H 'Content-Type: application/json' \
-d '{"username":"admin","password":"wrong"}' -w ' [HTTP %{http_code}]'
{"err":"Invalid credentials"} [HTTP 401]
连续失败后触发指数退避限流，实测从第二次失败起返回：
{"err":"You are being rate limited"} [HTTP 429]
⚠️ 注意：未经认证直接访问 API 会得到
{"err":"Invalid Authorization header format"}，登录令牌通过Authorization: Bearer <token>头随请求携带，服务端签发的令牌有效期约 730 小时（一个月）。
六、上传与浏览验证
部署是否真正可用，以目录浏览与文件上传两项核心操作实测为准。以下示例均携带上一步取得的令牌（以 $TOKEN 表示）。
6.1 浏览目录
curl -s http://127.0.0.1:8148/api/browse/ -H "Authorization: Bearer $TOKEN"
实测回显（数据目录中已预置两个测试文件）：
{"fileInfos":[{"isDir":false,"size":14,"path":"/hello.txt"},{"isDir":false,"size":0,"path":"/sample.bin"}],"isRoot":true}
6.2 创建目录与上传
创建子目录 docs，并以 multipart 表单（字段名固定为 file）上传一个 2KB 测试文件：
curl -s -X PUT http://127.0.0.1:8148/api/mkdir/docs -H "Authorization: Bearer $TOKEN"
curl -s -X PUT http://127.0.0.1:8148/api/upload/docs/report.md \
-F "file=@./data/hello.txt" -H "Authorization: Bearer $TOKEN"
实测回显：
{"status":"ok"}
{"status":"ok"}
再次浏览 docs 目录确认落盘：
curl -s http://127.0.0.1:8148/api/browse/docs -H "Authorization: Bearer $TOKEN"
{"fileInfos":[{"isDir":false,"size":14,"path":"/docs/report.md"}],"isRoot":false}
宿主机对应目录同步可见（bind mount 直接映射，ls data/docs 输出 report.md）。
6.3 模糊搜索与下载
搜索（search 参数在当前目录子树内模糊匹配）：
curl -s "http://127.0.0.1:8148/api/browse/?search=sam" -H "Authorization: Bearer $TOKEN"
{"fileInfos":[{"isDir":false,"size":2048,"path":"/sample.bin"}],"isRoot":true}
目录打包下载（对目录路径请求流式接口，自动打包为 tar.gz）：
curl -s "http://127.0.0.1:8148/api/stream/docs?auth=$SD" -o docs.tar.gz -w '[HTTP %{http_code}] bytes=%{size_download}\n'
[HTTP 200] bytes=124
docs.tar.gz: gzip compressed data, original size modulo 2^32 2048
/report.md
（$SD 为对 /docs 申请的流式令牌，申请方式见 D 篇 API 使用详解。）
七、数据持久化说明
mikochi 是无状态服务，唯一需要持久化的就是 DATA_DIR 挂载目录：
- bind mount 方案（本文采用）：宿主机目录直接映射到服务内
/data，数据落在宿主机文件系统，备份（rsync/tar）与迁移（改路径）都最直观； - named volume 方案：
volumes: [mikochi-data:/data]，由编排工具管理存储位置，适合不想关心宿主机路径的场景。
服务重启、重建均不影响 DATA_DIR 内数据；文件的元信息（文件列表索引）在服务内内存中随目录变化实时重建，同样无需持久化。
⚠️ 注意：不要把系统根目录或含敏感凭据的目录挂为
DATA_DIR——官方安全须知明确提示此举在服务被攻破时后果严重。
八、环境变量表
部署可用的全部环境变量（默认值取自官方源码 main.go 的启动配置，实测值以 1.12.2 为准）：
| 变量 | 作用 | 默认值 | 本文取值 |
|---|---|---|---|
| DATA_DIR | 被浏览的根目录 | /data | /data（挂载宿主机目录） |
| USERNAME | 登录用户名 | root | admin |
| PASSWORD | 登录密码 | pass | q1w2e3r4 |
| HOST | 监听地址与端口 | 0.0.0.0:8080 | 默认（映射 8148） |
| JWT_SECRET | JWT 签名密钥 | 随机生成 | 默认（每次重启随机） |
| CERT_CA | TLS 证书路径 | 空（未启用） | 未启用 |
| CERT_KEY | TLS 证书私钥路径 | 空（未启用） | 未启用 |
| NO_AUTH | 关闭认证 | false | 默认 |
| GZIP | 响应 gzip 压缩 | false | 默认 |
| FRONTEND_FILES | 前端静态文件目录 | /usr/share/mikochi/static | 默认 |
各变量的详细行为、实测对照与生产建议见 《mikochi 1.12.2 配置参数详解》。
九、等价 docker run 命令
与上述编排文件等效的单条启动命令（来源为官方 README 的最小示例，凭据改用本文演示值）：
docker run -d \
--name mikochi-1.12.2-web \
-p 8148:8080 \
-v /opt/data/quzuo/tmp/mikochi/data:/data \
-e DATA_DIR="/data" \
-e USERNAME=admin \
-e PASSWORD=q1w2e3r4 \
--restart unless-stopped \
zer0tonin/mikochi:1.12.2
单机自用与编排文件二选一即可；需要固定子网、纳入统一编排管理时建议用 Compose。
十、常用运维命令
以下命令均在编排文件所在目录执行（compose 语境，作用对象为本栈）：
docker compose ps # 栈内服务状态
docker compose logs -f web # 跟踪服务日志
docker compose restart web # 重启服务
docker compose down # 停止并移除栈（网络/容器，不影响 data 目录）
docker compose up -d # 修改编排/版本后重建
docker compose logs 实测回显（节选，Gin 请求日志逐请求一行）：
[GIN] 2026/10/30 - 08:02:12 | 200 | 72.341µs | 10.89.56.1 | GET "/api/stream-token?target=/sample.bin"
[GIN] 2026/10/30 - 08:02:12 | 200 | 93.6µs | 10.89.56.1 | GET "/api/stream/sample.bin?auth=eyJ..."
2026/10/30 08:02:12 Failed login attempt for victim
[GIN] 2026/10/30 - 08:02:12 | 429 | 58.012µs | 10.89.56.1 | POST "/api/login"
日志可直接看到请求耗时、来源地址、命中端点与登录失败告警，无需额外配置即可用于日常巡检。
十一、常见问题
Q1：服务重启后，之前登录的浏览器全部要求重新登录？
这是正常现象。JWT_SECRET 未显式设置时每次启动随机生成（官方有意为之，防止多进程共享固定密钥），重启后旧令牌签名失效。实测：重启前签发的令牌在重启后请求返回 {"err":"Failed to parse token"} [HTTP 401]，重新登录即恢复。需要令牌跨重启有效时，显式固定 JWT_SECRET（注意固定密钥的安全代价，见配置篇）。
Q2：上传接口报 Couldn't read file from request？
上传端点要求 multipart 表单且字段名必须是 file。实测用 --data-binary 直传二进制体必报此错，改用 -F "file=@本地文件" 即成功返回 {"status":"ok"}。
Q3：流式链接在 VLC 里打不开？
流式令牌与申请时指定的目标路径一一绑定（scope 即文件路径），换文件必须重新申请；且令牌通过 auth 查询参数携带（不是 token 参数），实测传错参数名会得到 {"err":"Failed to parse token"}。完整申请与播放链路见 D 篇。
Q4：访问首页一直转圈或空白？
首页是 489 字节的 SPA 入口（实测 Content-Type: text/html; charset=utf-8），后续由浏览器加载 assets 下静态资源渲染。若静态资源 404，检查 FRONTEND_FILES 是否被改坏（默认 /usr/share/mikochi/static，容器内路径不建议动）。
Q5：删除操作能撤销吗？ 不能。删除对应递归真删（含目录），且服务不提供回收站。重要数据请依赖宿主机层面的备份策略。
十二、参考链接
- GitHub 仓库（部署与配置说明）：https://github.com/zer0tonin/Mikochi （查询日期 2026-10-30）
- Docker Hub 镜像页：https://hub.docker.com/r/zer0tonin/mikochi
- Release 1.12.2 说明：https://github.com/zer0tonin/Mikochi/releases/tag/1.12.2
- 站内相关文档：《mikochi 介绍与选型指南》、《mikochi 1.12.2 配置参数详解》、《mikochi 1.12.2 API 使用详解》