企业官网建设流程全解析

Files.md Docker部署完全指南：Dockerfile、compose与卷设计逐行讲解

【免费下载链接】files.md🌱 Private, quiet space for thinking. Simple app for .md files.项目地址: https://gitcode.com/GitHub_Trending/fi/files.md

Files.md 是一个私密、安静的 Markdown 笔记空间，而自托管服务端正是它数据同步与多设备协作的核心。本文带你逐行拆解它的 Dockerfile 与 compose.yaml：从多阶段构建、非 root 运行，到 storage / tokens 两大卷的设计意图，最后附一键启动与 HTTPS 开启步骤。无需深厚 Docker 背景，跟着读一遍就能在自己机器上跑起 Files.md 服务端。

为什么 Files.md 值得自己部署

Files.md 的服务端承担两个角色（见 cmd/server/server.go）：

1. 托管 PWA 网页应用——你在浏览器里打开的笔记界面；
2. 提供同步 API——让多台设备上的 Markdown 文件保持一致（可选，配合 Telegram 机器人）。

用 Docker 部署的最大好处是：一条命令启动、配置即文件、升级与备份都清晰。下面进入正题。

Dockerfile 逐行解析：多阶段构建

整个构建分两阶段，源码见 Dockerfile。

构建阶段：只负责编译，不留下垃圾

FROM golang:1.24-alpine AS build WORKDIR /src COPY go.mod go.sum ./ RUN go mod download COPY . . ARG VERSION=dev RUN CGO_ENABLED=0 GOOS=linux go build \ -ldflags "-s -w -X main.Version=${VERSION}" \ -o /out/server ./cmd/server

关键点：

• COPY go.mod go.sum ./单独一层：依赖没变时复用缓存，二次构建飞快，这是 Go 项目的标准优化写法；
• CGO_ENABLED=0：产出静态链接的二进制，不依赖 glibc，为后续塞进极简的 alpine 镜像铺路；
• -s -w：剥掉符号表和调试信息，二进制更小；
• ARG VERSION=dev：构建时可以用--build-arg VERSION=v1.0注入版本号，写进二进制便于排查线上跑的是哪个版本。

运行阶段：最小化 + 安全

FROM alpine:3.20 RUN apk add --no-cache ca-certificates tzdata && \ addgroup -g 1000 app && adduser -D -u 1000 -G app app WORKDIR /app COPY --from=build /out/server /app/server COPY web /app/web RUN mkdir -p /app/storage /app/tokens && chown -R app:app /app VOLUME ["/app/storage", "/app/tokens"] USER app ENTRYPOINT ["/app/server"]

这一阶段值得逐条品味：

• 运行镜像只有 alpine + 证书 + 时区包，编译工具链全部被丢在第一阶段，最终镜像体积极小，攻击面也小；
• adduser -u 1000：预建 UID 1000 的app用户。自托管场景下，很多人习惯用 1000 号用户挂主机目录，权限不会打架；
• COPY web /app/web：网页前端直接静态拷贝进镜像，服务端按 server/sync/webserver.go 里的路由把 PWA 托管出来，不需要额外的 Nginx；
• USER app：容器不以 root 运行，这是自托管服务的基本安全素养。

卷设计详解：storage 与 tokens 各装什么

VOLUME ["/app/storage", "/app/tokens"]声明了两个数据目录，理解它们是理解整个部署的关键：

两个目录都被显式声明为卷，意味着：即使你docker compose down重建容器，数据也不会被打包进可丢弃的镜像层。官方文档 docs/your-own-server.md 在"迁移服务器"一节也印证了这一点——迁移只需要打包这两个目录即可。

compose.yaml 逐行解析

配置文件见 compose.yaml，结构非常精简：

services: files-md: build: . image: files-md ports: - "80:8080" volumes: - storage:/app/storage - tokens:/app/tokens environment: APP_URL: http://localhost STORAGE_DIR: /app/storage TOKENS_DIR: /app/tokens CERT_DIR: "" restart: unless-stopped volumes: storage: tokens:

端口映射：80:8080 的由来

CERT_DIR为空时，服务监听8080（本地模式）；一旦设置CERT_DIR，则改为443（HTTPS）+ 80（ACME 验证），逻辑见 server/sync/webserver.go 和 server/sync/autocert.go。compose 里预留了被注释的# - "443:443"，就是为了这个切换。

环境变量：全部来自配置结构体

五个环境变量一一对应 server/config/config.go 中的Config字段：

• STORAGE_DIR/TOKENS_DIR：指定数据目录，与卷挂载点对齐（注意config.go的默认值其实是/tmp，compose 里必须显式覆盖，否则数据会写进易失路径）；
• APP_URL：网页应用的外访地址，用于校验请求 Host 与 CORS 白名单；
• API_URL（默认注释）：留空则同步 API 不启用，服务端只跑网页；想让多设备同步/Telegram 机器人落盘，把它解开并填上域名；
• CERT_DIR：见下一节。

restart: unless-stopped

宿主机重启或 Docker 守护进程重启后自动拉起服务，除非你手动docker compose down——自托管的"免 babysit"保险丝。

一键启动：从 clone 到访问

在服务器上执行：

git clone https://gitcode.com/GitHub_Trending/fi/files.md cd files.md docker compose up -d

构建完成后访问http://你的服务器IP，就能打开 Files.md 的 PWA 界面。首次打开是空的工作区，左侧栏即笔记目录，体验如下：

如果同步功能已启用（设置了API_URL），设备间会走syncFilenames/syncFile等接口，按 mtime 判断变更，迁移数据时 mtime 会被完整保留。

进阶：一条配置开启 HTTPS 自动证书

Files.md 内置了 Let's Encrypt 自动签证书能力（server/sync/autocert.go），改动只有两处：

1. compose.yaml中把CERT_DIR改成持久路径（如/app/certs），并追加一个卷挂载；
2. 取消# - "443:443"注释，同时保留 80 端口（ACME http-01 验证走 80）。

然后：

docker compose up -d

证书自动申请并缓存在CERT_DIR里，续签全自动——这也是cert_dir必须持久化的原因。

备份与迁移建议

• 日常备份只需docker run --rm -v files_md_storage:/d alpine tar czf /backup/storage.tgz -C /d .打包storage卷，tokens卷同理；
• 跨机迁移完整步骤（含"先停写、再打包、后更新客户端 ApiHost"）见 docs/your-own-server.md 的Transfer files to another server一节；
• 官方还推荐在 storage 里git init+ cron 每日提交，把笔记本身当版本库再保险一层。

部署完跑一段时间后，多窗口编辑、笔记互链的体验正是 Files.md 的看家功能：

小结

• Dockerfile：多阶段构建 + 静态二进制 + 非 root 用户，产物极小且干净；
• 卷：storage存笔记、tokens存登录态，是备份与迁移的全部关键；
• compose：80:8080是本地模式，设CERT_DIR即切换到 443 自动 HTTPS，API_URL决定是否开放同步 API；
• 一句话：docker compose up -d之后，你的 Markdown 私有云就跑起来了。

【免费下载链接】files.md🌱 Private, quiet space for thinking. Simple app for .md files.项目地址: https://gitcode.com/GitHub_Trending/fi/files.md