方舟 · Ark

Appearance

Docker 服务密钥与配置管理指南 ​

目标: 在保持“低摩擦”(Low Friction) 原则的前提下，建立一套统一、安全且易于维护的 Docker 服务配置与密钥管理方案，解决配置分散和密码明文硬编码的问题。

1. 核心原则 (Principles) ​

  1. 代码与配置分离: docker-compose.yml 中不应包含任何具体密码或 Token，所有敏感信息必须通过环境变量注入。
  2. 分层管理: 将“全局通用配置”（如域名、时区）与“服务私有配置”（如数据库密码）分离。
  3. SSOT (单一数据源): 所有的 .env 文件应当在本地（如 1Password/Bitwarden 或加密压缩包）有一份集中备份，服务器上仅作为运行时的副本。

2. 目录与文件结构 (Structure) ​

推荐采用 “服务独立 .env + 全局共享配置” 的模式。

2.1 推荐结构 ​

text
/srv/
├── .env                  # [全局] 共享变量 (DOMAIN, TZ, PUID, PGID)
├── core/
│   ├── .env              # [局部] Core 服务专用 (Portainer 密码, FRP Token)
│   ├── docker-compose.yml
│   └── ...
├── hub/
│   ├── .env              # [局部] Hub 服务专用 (MySQL, Nextcloud 密码)
│   ├── docker-compose.yml
│   └── ...
└── monitor/
    ├── .env              # [局部] Monitor 服务专用 (Grafana 密码)
    ├── docker-compose.yml
    └── ...

3. 配置实施方案 (Implementation) ​

3.1 全局配置 (/srv/.env) ​

存放所有容器通用的基础信息，减少重复定义。

bash
# /srv/.env
# 基础信息
TIMEZONE=Asia/Shanghai
DOMAIN=hongjy.cn
SERVER_IP=192.168.233.129
EMAIL=hongjy1991@gmail.com

# 权限控制 (当前用户 ID，防止权限问题)
PUID=1000
PGID=1000

3.2 服务级配置 (/srv/hub/.env) ​

存放该服务栈特有的敏感信息。

bash
# /srv/hub/.env
# 数据库密码 (使用强密码)
MYSQL_ROOT_PASSWORD=x7K9#mP2$vL5nQ8
MYSQL_USER_PASSWORD=z3B6@jR9!wS1cA4

# 应用密码
NEXTCLOUD_ADMIN_PASS=...

3.3 Docker Compose 引用方式 ​

在 docker-compose.yml 中，同时加载全局和局部的 .env 文件。

注意: env_file 的加载顺序很重要。后加载的文件会覆盖先加载的变量。

yaml
# /srv/hub/docker-compose.yml
version: '3.8'

services:
  nextcloud:
    image: nextcloud
    env_file:
      - ../.env       # 1. 加载全局配置 (TZ, PUID)
      - ./.env        # 2. 加载局部配置 (DB_PASSWORD)
    environment:
      - TZ=${TIMEZONE}
      - MYSQL_PASSWORD=${MYSQL_USER_PASSWORD}

4. 密码管理规范 (Password Policy) ​

不要再使用 Asdfg3.14159 这种简单且重复的密码。

4.1 生成强密码 ​

使用命令行工具生成随机强密码（32位+）：

bash
# 生成 32 字符的随机密码 (Base64 编码)
openssl rand -base64 24

# 或者使用 date + sha256 (如果不方便用 openssl)
date +%s | sha256sum | base64 | head -c 32

4.2 存储与备份 ​

  1. 主密码管理器: 推荐使用 1Password 或 Bitwarden。

  2. 安全笔记: 创建一个名为 "Homelab Server Config" 的安全笔记。

  3. 内容格式:

    text
    Server: 192.168.233.129
User: hongjy

[Global .env]
...

[Hub .env]
MYSQL_ROOT_PASSWORD=...
...

  4. 禁止提交: 确保 .env 文件被添加到 .gitignore 中，永远不要提交到 Git 仓库。仓库中只保留 .env.example。

5. 迁移与维护操作 (Operation Guide) ​

5.1 从现有环境迁移 ​

你现在的环境密码比较混乱，建议执行一次“大清洗”。

  1. 生成新密码: 为 MySQL, Postgres, Grafana 等所有服务生成全新的强密码。

  2. 更新 .env: 在服务器上创建上述结构的文件，填入新密码。

  3. 重建容器:

    bash
    # 停止并删除旧容器
docker compose down

# 如果数据库密码变了，可能需要手动重置数据库用户密码，或者(如果数据不重要)删除 volume 重建
# 注意：仅修改 .env 不会自动修改已运行数据库内的密码！

# 启动新环境
docker compose up -d

5.2 日常维护 ​

  • 修改配置: 直接编辑服务器上的 .env 文件，然后 docker compose up -d 即可生效。
  • 备份: 定期将服务器上的 /srv/**/.env 文件打包加密下载到本地备份。

6. 附录：常用变量命名推荐 ​

为了避免全局变量冲突，建议服务私有变量加上前缀：

  • 通用: TZ, PUID, PGID, LOG_LEVEL
  • MySQL: MYSQL_ROOT_PASSWORD, MYSQL_DATABASE, MYSQL_USER, MYSQL_PASSWORD
  • Postgres: POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB
  • Hub 服务: HUB_DB_PASSWORD, NEXTCLOUD_ADMIN_PASS
  • Monitor 服务: GRAFANA_ADMIN_PASS

方舟 · Ark

Copyright © 2026-present WhatHappenin