mikochi 1.12.2 配置参数详解

目标：本篇逐项讲透 mikochi 1.12.2 的全部配置入口——它没有配置文件，所有行为由环境变量驱动，本篇给出每个变量的默认值、实测行为（含 GZIP/NO_AUTH/TLS/JWT_SECRET 的对照实验回显）、生产推荐组合与易踩的坑，全部结论在真实环境实测通过。

一、环境信息

操作系统：Linux x86_64（内核 5.x 系列，Ubuntu 系发行版实测）
mikochi：1.12.2（官方镜像 zer0tonin/mikochi:1.12.2，digest sha256:65ee9bf2f5315cef6a8caafa6bf9528bf998807be8a9872a38bf3627dbb4791c）
编排方式：Docker Compose v5.6.1（Docker 29.9.2），栈 mikochi-1.12.2-stack
服务端口：宿主机 8148 → 服务内 8080
数据目录：宿主机目录挂载至 /data（DATA_DIR）
登录凭据：admin / q1w2e3r4（演示账号）
实测资源基线：空载状态 CPU 0.00%，常驻内存 3.656MiB（docker stats --no-stream 实测）——配置层面的任何优化对这个量级的服务来说更多是安全与行为正确性问题，而非性能问题
参数取证基准：官方源码 backend/main.go 的默认值设定 + 1.12.2 运行实例逐项实测（查询日期 2026-10-30）

二、前置条件

已按部署指南完成 1.12.2 实例搭建并可正常登录（见《mikochi 1.12.2 Docker Compose 部署指南》）；
能修改编排文件并 docker compose up -d 重建（本文所有"修改配置"均指改 environment 后重建，mikochi 无热加载）；
如实验 TLS，提前准备证书与私钥文件（自签证书即可，openssl req -x509 -newkey rsa:2048 一条命令生成）。

三、参数查看与修改方式

3.1 配置载体：纯环境变量

mikochi 没有任何配置文件。启动时通过 Go 的 viper 库读取环境变量，未设置的变量落到内置默认值（源码 viper.SetDefault），因此：

查看当前生效值：docker inspect mikochi-1.12.2-web --format '{{.Config.Env}}'（列出注入的环境变量）；默认值部分则需对照源码与本文表格；
修改：改编排文件 environment 段 → docker compose up -d 重建生效；
确认生效：多数变量通过行为差异验证（如 GZIP 看响应头、NO_AUTH 看免登录访问），本文各节均给出实测对照。

3.2 重建对状态的影响

重建（up -d 重建容器）会带来两个副作用，配置实验前要知道：

JWT_SECRET 未显式固定时随机重生，所有已签发登录令牌失效（实测见"6.4"节）；
文件索引随 DATA_DIR 重新扫描，挂载目录不变则数据无损。

四、参数总览

变量	作用	默认值（源码实测）	本篇实测状态
DATA_DIR	被浏览的根目录	`/data`	实测挂载生效
USERNAME	登录用户名	`root`	实测改为 `admin` 生效
PASSWORD	登录密码	`pass`	实测改为 `q1w2e3r4` 生效
HOST	监听地址与端口	`0.0.0.0:8080`	实测监听 8080（README 有笔误）
JWT_SECRET	JWT 签名密钥	随机生成	实测重启随机化、令牌失效
CERT_CA	TLS 证书路径	未设置（空）	实测启用 HTTPS
CERT_KEY	TLS 私钥路径	未设置（空）	实测启用 HTTPS
NO_AUTH	关闭全部认证	`false`	实测免认证访问
GZIP	响应 gzip 压缩	`false`	实测 `Content-Encoding: gzip`
FRONTEND_FILES	前端静态文件目录	`/usr/share/mikochi/static`	实测目录内容确认
ENV	Gin 运行模式	`production`	源码确认（README 未收录）

💡 说明：上表共 11 个变量，其中 ENV 只出现在源码而未被官方 README 的配置表收录；另官方 README 将 HOST 默认值写作 0.0.0.0:80，与源码 viper.SetDefault("HOST", "0.0.0.0:8080") 不一致——实测实例监听 8080（编排文件未设 HOST 的情况下 8148->8080 映射正常工作），以源码与实测为准，以 80 为默认值去写端口映射会连不上。

五、核心参数分类详解

5.1 数据与访问边界：DATA_DIR

DATA_DIR 定义 mikochi 世界的边界：浏览、上传、下载、流式播放全部限制在该目录子树内。实测把宿主机目录挂到服务内 /data 后，浏览接口返回的路径均以 /（即 DATA_DIR）为根：

{"fileInfos":[{"isDir":true,"size":4096,"path":"/docs"},{"isDir":false,"size":2048,"path":"/sample.bin"}],"isRoot":true}

实践建议：

挂载专用数据目录，一个实例一个根，边界清晰；
服务内进程以 root 运行，宿主机目录权限按需收紧（只读场景可挂 :ro，此时写操作会报错）；
禁止设为 /——官方安全须知原话是"这可能对系统完整性造成严重后果"。

5.2 登录凭据：USERNAME / PASSWORD

两个变量共同构成唯一的登录凭据组（mikochi 无多用户模型）。实测修改为 admin/q1w2e3r4 后：

POST /api/login {"username":"admin","password":"q1w2e3r4"} → 200 {"token":"eyJ..."}
POST /api/login {"username":"admin","password":"wrong"}   → 401 {"err":"Invalid credentials"}

要点：

源码默认 root/pass 属公开知识，暴露公网等于裸奔，必须覆盖；
认证只支持一组凭据：没有多用户、没有按目录授权，团队场景请评估其他产品（选型对比见《mikochi 介绍与选型指南》）；
密码错误按用户名做指数退避限流：第 1 次失败冷却 1 秒，此后每次失败冷却时间翻倍（源码 2^n 秒），实测第 2 次起直接 429 You are being rate limited；登录成功即重置计数。

5.3 监听地址：HOST

HOST 控制服务监听的 ip:port。默认 0.0.0.0:8080（实测成立），容器场景下通常不需要改它——改端口映射（"8148:8080"）比改变量更顺手。需要只监听内网网卡时才显式设置，如 HOST: "192.168.1.10:8080"。

5.4 令牌签名密钥：JWT_SECRET

JWT_SECRET 是登录令牌（JWT HS256）与流式令牌共用的签名密钥。未设置时每次启动随机生成，实测行为链：

重启前登录拿到的令牌；
docker compose up -d 重建后用旧令牌请求：{"err":"Failed to parse token"} [HTTP 401]；
重新登录即恢复。

这是官方有意的安全默认（防止固定密钥在多进程间共享、令牌吊销失效效），代价是重启等于全员重新登录。何时固定：多副本共享密钥（mikochi 本身无多副本需求）或希望重启不掉登录态时；固定时给足熵（长随机串），并把它当敏感凭据管理。部署篇的常见问题 Q1 也复述了这一行为。

5.5 TLS 证书：CERT_CA / CERT_KEY

两个变量成对使用，同时设置后服务直接以 HTTPS 提供服务（无需反向代理）。实测（自签证书挂载到 /certs/）：

environment:
  CERT_CA: "/certs/cert.pem"
  CERT_KEY: "/certs/key.pem"

验证一——HTTPS 正常服务：

curl -sk https://127.0.0.1:8148/ready
{"status":"ok"}
curl -sk -X POST https://127.0.0.1:8148/api/login -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}'
{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}（节选）

验证二——纯 HTTP 请求被明确拒绝：

curl -s http://127.0.0.1:8148/ready
Client sent an HTTP request to an HTTPS server. [HTTP 400]

💡 技术拓展：Web 文件服务的 TLS 有两条路径——服务端内置证书（本参数，适合内网自签、小规模直连）与反向代理终结 TLS（Traefik/Nginx/Caddy 统一管理证书与续期，mikochi 保持 HTTP，官方博客的 Docker+Traefik 教程即此方案）。公网生产建议后者：证书自动续期、多服务共用 443、还能顺手做访问控制。

5.6 免认证开关：NO_AUTH

NO_AUTH=true 时跳过全部认证中间件。实测表现：

curl -s http://127.0.0.1:8148/api/browse/          # 不带任何令牌
{"fileInfos":[{"isDir":true,"size":4096,"path":"/docs"},{"isDir":false,"size":2048,"path":"/sample.bin"}],"isRoot":true}

curl -s http://127.0.0.1:8148/api/refresh
{"token":"no_auth"}

适用与风险边界：

适用：纯内网、临时分发、由网关统一认证的场景；
风险：官方 README 明确警告"任何人都能往你的磁盘上传文件"，公网实例严禁开启；
版本背景：该开关在 1.12.1 及之前的补丁版本中一度失效（1.12.2 专门修复"Fixes disabling authentication with NO_AUTH=true"），升级到 1.12.2 才是完整可用语义。

5.7 响应压缩：GZIP

GZIP=true 启用响应体 gzip 压缩。实测对照（同一首页资源）：

默认（GZIP=false）：Content-Length: 489，无 Content-Encoding 头
GZIP=true：        Content-Encoding: gzip，Content-Length: 305

首页传输体积从 489 字节压到 305 字节。对这个体量的服务，压缩收益主要是弱网下静态资源与 JSON 响应的加载体验；已由反向代理统一压缩时保持默认 false 避免双重压缩。

5.8 前端静态文件：FRONTEND_FILES

指向 Preact 前端构建产物的目录，默认 /usr/share/mikochi/static（镜像内实测内容：assets/、favicon.ico、index.html、logo.png）。除自定义前端改造外不需要动它；误设后 SPA 入口 404，所有页面退化成"空白 + 404"，排障时先核对该路径。

5.9 运行模式：ENV

ENV=production（默认）时 Gin 切换到 Release 模式（关闭调试输出），设为其他值（如 debug）进入 Debug 模式。这是源码里存在而 README 未收录的变量，排障需要更详细日志时临时使用，生产保持默认。

六、生产配置模板

6.1 推荐模板（个人服务器/NAS，内存 512MB 起步即可，磁盘视数据量，场景=个人私用文件面板）

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"       # 换成强密码；密钥类建议用外部注入
      JWT_SECRET: "${JWT_SECRET}"  # 长随机串，从环境注入，见下方说明
      GZIP: "true"
    volumes:
      - /srv/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

模板要点逐条说明：

公网部署加一层反向代理终结 TLS（CERT_CA/CERT_KEY 留给纯内网直连 HTTPS 场景），凭据与令牌不裸奔在明文 HTTP 上；
固定 JWT_SECRET：用 echo "$(head -c 32 /dev/urandom | base64)" 生成后写入实例环境（通过 .env 文件或启动环境注入，避免明文进仓库），重启不掉登录态且签名密钥有足够熵；
凭据治理：PASSWORD 属敏感值，建议同样走 ${VAR} 注入而非明文进编排文件；
NO_AUTH 保持默认关闭，ENV 保持 production，FRONTEND_FILES 保持默认；
资源约束：实测空载内存 3.656MiB，小内存设备（如 512MB 的盒子）也能稳定运行，无需专门调参。

6.2 纯内网 HTTPS 直连模板（差异片段）

    environment:
      CERT_CA: "/certs/cert.pem"
      CERT_KEY: "/certs/key.pem"
    volumes:
      - /srv/mikochi/data:/data
      - /srv/mikochi/certs:/certs:ro

实测该形态下 HTTPS 接口正常、HTTP 请求 400 拒绝（见 5.5 节回显），适合没有统一网关的内网环境。

七、常见问题

Q1：改了环境变量为什么没生效？ 环境变量在服务启动时读取，没有热加载。改完 environment 必须 docker compose up -d 重建（compose 检测到配置差异会自动重建）；只 restart 不重建不会重读编排文件的变量变更。

Q2：HOST 按 README 设成 8080 之外端口后映射不通？ 优先检查是不是把"服务内端口"与"映射端口"搞混：容器内监听由 HOST 决定（默认 8080），外部访问端口由映射决定（8148:8080 的前者）。README 把默认值写成 0.0.0.0:80 是笔误，实测默认就是 8080。

Q3：固定 JWT_SECRET 后还有哪些注意点？ 固定后重启不再掉登录态，但密钥本身成了高价值目标：泄露意味着攻击者可自签任意令牌。管理上与密码同级——不进代码仓库、不进日志、定期轮换（轮换即全员重新登录）。

Q4：想多人使用怎么办？ 配置层面无解——凭据就是一组。要么共享同一账号（无审计无隔离），要么换多用户产品（FileBrowser/FileGator 类，对比见 A1 篇）。

Q5：GZIP 开了以后个别请求没压缩？ gzip 只对可压缩类型生效，二进制上传/下载体不压缩属正常；经反向代理时留意代理层自己的压缩开关，避免叠加。

八、参考链接

官方 README 配置表与安全须知：https://github.com/zer0tonin/Mikochi （查询日期 2026-10-30）
源码默认值基准：https://github.com/zer0tonin/Mikochi/blob/main/backend/main.go
Release 1.12.2（NO_AUTH 修复）：https://github.com/zer0tonin/Mikochi/releases/tag/1.12.2
站内相关文档：《mikochi 1.12.2 Docker Compose 部署指南》、《mikochi 介绍与选型指南》、《mikochi 1.12.2 API 使用详解》