一、镜像

金仓的镜像不挂在公共仓库，来源一般是两个：

• 厂商给的镜像 tar 包，docker load -i kingbase-v8r6.tar 导入
• 内部私有仓库，docker pull <仓库地址>/kingbase:v8r6

导入后确认：

docker images | grep -i kingbase

镜像名和 tag 按实际导入的写，后面的 compose 里统一用 kingbase:v8r6 举例。

二、目录规划

sudo mkdir -p /data/kingbase/{data,license}

容器内的安装目录不是统一的，先看一眼实际布局再写挂载路径：

docker run --rm --entrypoint ls kingbase:v8r6 /home/kingbase/install/kingbase

常见的几处：

• 安装目录：/home/kingbase/install/kingbase
• 授权文件：/home/kingbase/install/kingbase/bin/license.dat
• 服务端程序：同目录下的 bin/kingbase、bin/sys_ctl、bin/ksql
• 数据目录：由镜像或 entrypoint 决定，通常在 kingbase 用户主目录下

数据目录的属主要和容器里的 kingbase 用户对上：

docker run --rm --entrypoint id kingbase:v8r6 kingbase
sudo chown -R <输出的uid>:<输出的gid> /data/kingbase/data

三、启动

services:
  kingbase:
    image: kingbase:v8r6
    container_name: kingbase8
    restart: unless-stopped
    privileged: true
    environment:
      TZ: Asia/Shanghai
      DB_MODE: mysql
    ports:
      - "54321:54321"
    volumes:
      - /data/kingbase/data:/home/kingbase/data
      - /data/kingbase/license/license.dat:/home/kingbase/install/kingbase/bin/license.dat
    shm_size: 1gb

几点说明：

1. DB_MODE 决定兼容模式（Oracle / MySQL / PG），建库前定好，后面改不了。用 MySQL 兼容模式就写 mysql。
2. privileged 和 command: /usr/sbin/init：有的厂商镜像把完整系统打包进来，用 systemd 启动，这种镜像必须开特权模式。如果镜像是单进程启动的，这两项可以去掉，以 docker inspect 看到的 entrypoint 为准。
3. shm_size 默认只有 64 MB，跑并发查询时容易报共享内存不足，给到 1 GB 比较稳。
4. 端口映射写成 127.0.0.1:54321:54321 更安全，只给本机或反向代理访问。

四、license 的三个坑

金仓只在启动时校验授权，运行中的实例不会因为到期被踢出去，但下一次重启就起不来。这是它和普通数据库最不一样的地方。

坑一：license 在容器可写层里

不挂卷的时候，license 的实体在容器内的安装目录下。docker restart 能保住，docker rm 之后重建，就退回镜像里那份旧证。镜像里那份往往是打包时的临时授权，可能早就过期了。

所以 license 要单独挂出来：

    volumes:
      - /data/kingbase/license/license.dat:/home/kingbase/install/kingbase/bin/license.dat

坑二：挂载不能加 :ro

这个镜像的 entrypoint 启动时会对安装目录做 chown。挂载点设成只读，chown 直接失败：

chown: changing ownership of '/home/kingbase/install/kingbase/bin/license.dat': Read-only file system

随后服务起不来，报 sys_ctl: could not start server。所以 license 的挂载必须是可写的。

坑三：宿主机文件要先存在

如果宿主机上 license.dat 不存在，Docker 会把挂载点创建成一个目录，容器里的金仓读到目录，报错形态和"授权无效"完全不一样，很容易查错方向。

顺序必须是：

# 1. 先放文件
sudo cp license_xxx.dat /data/kingbase/license/license.dat
# 2. 改属主，和容器内 kingbase 用户一致
sudo chown <uid>:<gid> /data/kingbase/license/license.dat
chmod 640 /data/kingbase/license/license.dat
# 3. 再改 compose 挂载

改完挂载启动，容器内 entrypoint 那次 chown 会真的改掉宿主机文件的属主，这是 bind mount 共享 inode 的正常结果，不是事故。

五、初始化

多数厂商镜像的 entrypoint 会在数据目录为空时自动 initdb，已经有数据就跳过。手工初始化也可以，用 kingbase 用户执行：

docker exec -u kingbase kingbase8 \
  /home/kingbase/install/kingbase/bin/initdb \
  -D /home/kingbase/data -U SYSTEM --pwfile=/tmp/pw

-U 指定超级用户，后面所有连接都用这个用户名。--pwfile 里放初始密码，不要用 -W 交互输入，容器里没有终端。

注意 initdb 的字符集和兼容模式要和 DB_MODE 一致，建库之后再改，等于重建。

六、验证库到底起没起

这一步最容易被误导。sys_ctl 在 license 校验之前就把 pid 文件写出来了，所以日志里出现 server started，不代表库活着。判定存活只看这三条：

# 1. 进程状态，退出码为 0 才算
docker exec -u kingbase kingbase8 \
  /home/kingbase/install/kingbase/bin/sys_ctl status -D /home/kingbase/data

# 2. 端口在监听。这个镜像里可能没有 ss/netstat，直接看 /proc
docker exec kingbase8 grep -i ':D431' /proc/net/tcp /proc/net/tcp6

# 3. 日志里出现 ready 字样
docker exec kingbase8 tail -50 /home/kingbase/data/sys_log/*.log

54321 的十六进制是 0xD431，这也是为什么要在 /proc/net/tcp 里搜这个字符串。容器里没有 ss 的时候，docker exec kingbase8 ss -lntp 会静默无输出，不能当成"端口没监听"。

三条都过了，再连库：

docker exec -u kingbase kingbase8 \
  ksql -U SYSTEM -p 54321 -d test -c "select version();"

镜像的 entrypoint 在 initdb 时会把本地连接认证改成 trust，容器内连库不需要密码。外网连接受 kingbase.conf 里的 listen_addresses 和 sys_hba.conf 控制，默认只允许本地。

七、换 license 的标准动作

授权到期后，启动日志是这样的：

FATAL: XX000: License file expired.
LOCATION: KesMasterMain, master.c:961

换证按顺序做，少一步就会遇到"换了还是起不来"：

# 1. 备份旧证和当前配置
sudo cp -a /data/kingbase/license/license.dat \
  /data/kingbase/license/license.dat.bak-$(date +%F)

# 2. 覆盖新证，注意保住 inode 和属主
sudo cat new_license.dat > /data/kingbase/license/license.dat
sudo chown <uid>:<gid> /data/kingbase/license/license.dat

# 3. 清掉上次启动失败留下的 socket 和 pid 残留
docker exec kingbase8 sh -c '
  ts=$(date +%s)
  mkdir -p /tmp/kingbase-stale-$ts
  mv /tmp/.s.KINGBASE.54321* /tmp/kingbase-stale-$ts/ 2>/dev/null || true'

# 4. 用 kingbase 用户启动，root 会被拒绝
docker exec -u kingbase kingbase8 \
  /home/kingbase/install/kingbase/bin/sys_ctl start -D /home/kingbase/data

用 cat > 就地覆盖而不是删除重写，是为了保住文件 inode，已经挂载的路径不用重建容器。/tmp/.s.KINGBASE.54321 和对应的 .lock 文件是上次启动失败留下的，不清掉会报：

another server might be running; trying to start server anyway
lock file "/tmp/.s.KINGBASE.54321.lock" already exists

残留文件用 mv 挪走而不是 rm，出问题时还能看一眼时间戳，判断上一次启动尝试发生在什么时候。

还有一条：镜像里通常挂着一个 cron 看门狗，每分钟尝试拉起数据库。手工启动时如果撞上它，会看到 another server is running，等一分钟再试，或者先停掉看门狗。

八、备份

逻辑备份用 sys_dump，参数和 PostgreSQL 的 pg_dump 基本一致：

docker exec -u kingbase kingbase8 \
  sys_dump -U SYSTEM -p 54321 -d app -F c -f /tmp/app.dump
docker cp kingbase8:/tmp/app.dump /backup/app-$(date +%F).dump

恢复：

docker cp /backup/app-2026-10-29.dump kingbase8:/tmp/app.dump
docker exec -u kingbase kingbase8 \
  sys_restore -U SYSTEM -p 54321 -d app /tmp/app.dump

数据库本身可以直接停库后复制数据目录，但和 MySQL 一样，热复制没有意义。

九、常见报错

十、限制

• 授权是硬中断：到期不影响运行中的实例，但任何一次重启、宿主机重启、容器重建都会当场起不来。到期日要单独记，别等出事再查。
• 授权可能带并发连接数上限，配置里写再大也会被压下来，这个值只能问发证方。
• 容器重建会退回镜像内的旧授权，所以 license 必须挂卷，且换证后要检查挂载是否还在。
• 单实例部署没有高可用，做主备是另一套配置（sys_hba.conf、复制槽、recovery.conf 这一套），不在容器化本身的范围里。

一、镜像和目录

docker pull mysql:8.0
sudo mkdir -p /data/mysql/{data,conf,init}

/data/mysql/data 要给容器里的 mysql 用户（uid 999）权限：

sudo chown -R 999:999 /data/mysql/data

如果数据目录挂的是新格式化的独立分区，注意分区根目录里会有 lost+found。MySQL 初始化时要求目录为空，看到 lost+found 就认为"目录里有文件"，直接放弃初始化。这种情况用分区下的子目录，比如 /data/mysql/data，而不是直接把分区挂到 /var/lib/mysql。

二、my.cnf

/data/mysql/conf/my.cnf：

[mysqld]
character-set-server = utf8mb4
collation-server = utf8mb4_0900_ai_ci
lower_case_table_names = 1
default-time-zone = '+08:00'

max_connections = 500
innodb_buffer_pool_size = 1G

slow_query_log = 1
long_query_time = 1

几个参数说明：

配置文件权限有要求：MySQL 会忽略全局可写的配置文件。挂进去之后再确认一次：

sudo chmod 644 /data/mysql/conf/my.cnf

日志里出现 World-writable config file '/etc/mysql/conf.d/my.cnf' is ignored，就是权限太松，配置压根没被读。

三、compose

services:
  mysql:
    image: mysql:8.0
    container_name: mysql
    restart: always
    ports:
      - "3306:3306"
    environment:
      TZ: Asia/Shanghai
      MYSQL_ROOT_PASSWORD: 换成强密码
      MYSQL_DATABASE: app
      MYSQL_USER: app
      MYSQL_PASSWORD: 换成强密码
    volumes:
      - /data/mysql/data:/var/lib/mysql
      - /data/mysql/conf:/etc/mysql/conf.d:ro
      - /data/mysql/init:/docker-entrypoint-initdb.d:ro
    healthcheck:
      test: ["CMD-SHELL", "mysql -uroot -p\"$$MYSQL_ROOT_PASSWORD\" -e 'SELECT 1' >/dev/null 2>&1"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 60s

四个环境变量的实际行为：

healthcheck 这里用的是 mysql -e 'SELECT 1'，不是 mysqladmin ping。mysqladmin ping 只要服务端能响应就返回成功，密码错了也照样"通"，检测不出认证问题。

start_period 给 60 秒是有必要的，首次初始化要建系统表，磁盘慢的机器上跑一两分钟很正常，这段时间里的失败不该算进 retries。

四、初始化脚本

/data/mysql/init/ 下的 .sql、.sh 文件只在数据目录为空时按字母顺序执行一次。常见的用法是建库、建只读账号：

CREATE DATABASE IF NOT EXISTS app DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
CREATE USER IF NOT EXISTS 'readonly'@'%' IDENTIFIED BY '只读密码';
GRANT SELECT ON app.* TO 'readonly'@'%';
FLUSH PRIVILEGES;

放进去之后想让它再跑一遍，只能删数据目录重建，没有别的办法。所以初始化脚本要么一次写全，要么后面手工执行 SQL，不要指望"补一个文件进去重启就好"。

五、验证

docker ps --filter name=mysql
docker exec mysql mysql -uroot -p'密码' -e "SELECT VERSION(), @@character_set_server, @@lower_case_table_names, @@time_zone;"
docker exec mysql mysql -uroot -p'密码' -e "SHOW DATABASES;"

四个值对上了，说明配置文件和初始化参数都生效：

8.0.x   utf8mb4   1   +08:00

再从外部连一次，确认端口映射和账号授权：

mysql -h 127.0.0.1 -P 3306 -uapp -p'密码' app

六、备份和恢复

逻辑备份，适合中小库和跨版本迁移：

docker exec mysql sh -c 'exec mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" \
  --single-transaction --routines --triggers --events --set-gtid-purged=OFF app' \
  > /backup/app-$(date +%F).sql

--single-transaction 让 InnoDB 在一致性快照里导出，不锁表；--set-gtid-purged=OFF 避免恢复时报 GTID 冲突。

恢复：

docker exec -i mysql sh -c 'exec mysql -uroot -p"$MYSQL_ROOT_PASSWORD" app' < /backup/app-2026-10-29.sql

物理备份可以直接复制 /data/mysql/data，但必须在停库之后：

docker compose stop mysql
sudo tar -czf /backup/mysql-data-$(date +%F).tar.gz -C /data/mysql data
docker compose start mysql

热复制数据目录得到的文件不可用，InnoDB 的 redo 和双写缓冲在运行中不一致，恢复时会报错。

七、常见报错

八、8.4 和迁移

如果准备用 8.4，先确认客户端兼容性：mysql_native_password 在 8.4 里默认不加载，老版本驱动和工具连上来会失败。新项目直接用 8.4 没问题，存量系统升级前要在测试环境把驱动、中间件、备份脚本都过一遍。

跨大版本迁移（5.7 → 8.0）不要靠复制数据目录，走 mysqldump 导出再导入，或者用官方的 mysqlsh 升级检查工具，先把不兼容项列出来。

最后一条限制：容器里的 MySQL 性能和裸机没有本质区别，瓶颈仍然是磁盘 IO 和内存。把数据目录放在网络存储（NFS、CIFS）上跑 MySQL 属于高风险操作，遇到 fsync 语义不一致会直接损坏数据，这一点和容器无关，但容器化之后更容易被顺手挂上去。

一、镜像、端口和目录

docker pull minio/minio:latest
sudo mkdir -p /data/minio/data

正式环境不要用 latest，把 tag 固定到具体的 RELEASE 版本，升级时才有据可查。

二、启动

docker run -d --name minio \
  -p 9000:9000 -p 9001:9001 \
  -v /data/minio/data:/data \
  -e MINIO_ROOT_USER=admin \
  -e MINIO_ROOT_PASSWORD='至少八位的密码' \
  -e TZ=Asia/Shanghai \
  --restart=always \
  minio/minio:latest server /data --console-address ":9001"

三个参数不能少：

1. server /data：告诉 MinIO 数据目录在哪，容器里就是 /data，必须挂出来。
2. --console-address ":9001"：不给的话控制台端口是随机的，docker ps 里还要再查一次。
3. MINIO_ROOT_USER / MINIO_ROOT_PASSWORD：不设的话会用默认的 minioadmin / minioadmin，这是公认的默认口令，必须改。用户名至少 3 位，密码至少 8 位，不满足时容器启动即退出。

老资料里的 MINIO_ACCESS_KEY / MINIO_SECRET_KEY 已经废弃，写了也不生效，直接用 MINIO_ROOT_*。

三、compose 版本

services:
  minio:
    image: minio/minio:latest
    container_name: minio
    restart: always
    ports:
      - "9000:9000"
      - "9001:9001"
    environment:
      TZ: Asia/Shanghai
      MINIO_ROOT_USER: admin
      MINIO_ROOT_PASSWORD: 至少八位的密码
    volumes:
      - /data/minio/data:/data
    command: server /data --console-address ":9001"
    healthcheck:
      test: ["CMD", "mc", "ready", "local"]
      interval: 30s
      timeout: 10s
      retries: 3

密码写在 compose 里等于写在文件里，权限收到 600，或者用 env_file 单独放：

sudo chmod 600 /data/minio/docker-compose.yml

四、验证

容器起来后，先看健康检查接口，这个不需要认证：

curl -i http://127.0.0.1:9000/minio/health/live

返回 200 OK 说明服务在跑。然后进控制台 http://服务器IP:9001，用上面设置的用户名密码登录，能建桶就说明读写正常。

再看一眼数据目录，首次启动后 /data/minio/data 下会出现 .minio.sys：

ls -la /data/minio/data

如果这里报权限问题，先确认容器内进程的 uid：

docker exec minio id
sudo chown -R <uid>:<gid> /data/minio/data

五、用 mc 管理

mc 是 MinIO 的客户端，单文件二进制，和 Docker 无关，装在宿主机或运维机上：

mc alias set local http://127.0.0.1:9000 admin '密码'
mc admin info local

常用的几条：

mc mb local/backup                 # 建桶
mc ls local                        # 列桶
mc ls local/backup                 # 列对象
mc cp app.tar.gz local/backup/     # 上传
mc cp local/backup/app.tar.gz ./   # 下载
mc rm local/backup/old.tar.gz      # 删除
mc mirror ./dist local/static      # 目录同步，增量
mc du local/backup                 # 统计用量

mc mirror 是最实用的一个，可以把它当成对象存储版的 rsync，做目录发布和备份都行。加 --remove 会删掉目标端多余的文件，用之前确认方向别写反。

六、反向代理

API 和控制在同一个域名下，用路径区分：

server {
    listen 443 ssl;
    server_name s3.example.com;

    client_max_body_size 0;
    proxy_request_buffering off;
    proxy_buffering off;

    location / {
        proxy_pass http://127.0.0.1:9000;
        proxy_http_version 1.1;
        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;
    }

    location /minio/ {
        proxy_pass http://127.0.0.1:9001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $http_host;
    }
}

client_max_body_size 0 是必须的：MinIO 上传大对象时走的是分片，但单个分片也可能超过 Nginx 默认的 1 MB，不放开就会遇到 413。proxy_buffering off 是为了避免大文件先落到 Nginx 的临时目录。

控制台那一段必须带 Upgrade 和 Connection 头，否则页面能打开但登录后一直转圈，因为控制台的 WebSocket 连不上。

反代之后还要告诉 MinIO 外部访问地址，否则登录后跳转和预签名 URL 会指向内网地址：

    environment:
      MINIO_SERVER_URL: https://s3.example.com
      MINIO_BROWSER_REDIRECT_URL: https://s3.example.com/minio/

七、备份

MinIO 的数据是对象文件，直接 cp 数据目录并不可靠，尤其在有写入的时候。用客户端做：

mc mirror --overwrite local/important /backup/minio/important

或者用 mc admin 的导出功能搬全量，数据量大的场景更推荐在存储层做快照，或者上分布式多副本。

八、常见报错

九、边界

单机单盘模式没有冗余，磁盘坏了数据就没了，也没有纠删码。MinIO 的分布式模式至少需要 4 块盘（4 个目录也行），部署形态和多副本策略是另一套东西，单机跑起来之后再往上加节点并不平滑。

另外，MinIO 不是文件服务器，它存的是对象。需要像 Windows 共享目录那样挂载到本地盘的场景，它不合适，得配 S3 网关或者换别的方案。

如果只是给应用做附件、备份包、镜像层这类存储，单机模式配好备份就足够用了。

一、镜像和目录

docker pull redis:7.2
sudo mkdir -p /data/redis/{conf,data}

官方镜像默认以 redis 用户（uid 999）运行，/data 要能让它写：

sudo chown -R 999:999 /data/redis/data

宿主机目录属主不改成 999，后面要么存 RDB 失败，要么直接起不来。

二、先起一个空壳验证

先在没有任何配置的情况下跑一遍，确认镜像和端口没问题：

docker run -d --name redis-test -p 6379:6379 redis:7.2
docker exec redis-test redis-cli ping

返回 PONG 就说明镜像正常。验证完删掉，正式部署要带配置文件和密码：

docker rm -f redis-test

三、redis.conf

/data/redis/conf/redis.conf：

bind 0.0.0.0
protected-mode yes
port 6379
timeout 0
tcp-keepalive 300

requirepass 换成你的强密码

daemonize no
loglevel notice
logfile ""

dir /data

# RDB
save 900 1
save 300 10
save 60 10000
rdbcompression yes
dbfilename dump.rdb

# AOF
appendonly yes
appendfsync everysec
no-appendfsync-on-rewrite no
auto-aof-rewrite-percentage 100
auto-aof-rewrite-min-size 64mb

# 内存
maxmemory 512mb
maxmemory-policy allkeys-lru

几个参数的作用：

requirepass 写在配置文件里，不要写在 docker run 的 --requirepass 参数上，否则 docker inspect 和 ps 里都能直接看到。

四、docker run 或 compose

docker run 版本：

docker run -d --name redis \
  -p 6379:6379 \
  -v /data/redis/conf/redis.conf:/usr/local/etc/redis/redis.conf:ro \
  -v /data/redis/data:/data \
  -e TZ=Asia/Shanghai \
  --restart=always \
  redis:7.2 redis-server /usr/local/etc/redis/redis.conf

compose 版本：

services:
  redis:
    image: redis:7.2
    container_name: redis
    restart: always
    ports:
      - "6379:6379"
    environment:
      TZ: Asia/Shanghai
      REDIS_PASSWORD: 换成你的强密码
    command: ["redis-server", "/usr/local/etc/redis/redis.conf"]
    volumes:
      - /data/redis/conf/redis.conf:/usr/local/etc/redis/redis.conf:ro
      - /data/redis/data:/data
    healthcheck:
      test: ["CMD-SHELL", "redis-cli --no-auth-warning -a \"$$REDIS_PASSWORD\" ping | grep -q PONG"]
      interval: 30s
      timeout: 5s
      retries: 3

两处说明：

1. healthcheck 里的 $$ 是 compose 的转义，最终传给容器的是 $REDIS_PASSWORD，由 shell 展开。写成单个 $ 会被 compose 在解析阶段替换掉，密码就丢了。
2. 配置文件里已经写了 requirepass，环境变量 REDIS_PASSWORD 只是为了给健康检查用，两边的值要一致，改密码时一起改。

command 一定要带配置文件路径。不带的话镜像会用自己的默认配置启动，requirepass、appendonly 全部不生效，看起来容器起得好好的，实际是个没有密码的空库。

五、验证

# 不带密码访问，应该被拒绝
docker exec redis redis-cli ping
# NOAUTH Authentication required.

# 带密码
docker exec redis redis-cli --no-auth-warning -a "$(grep requirepass /data/redis/conf/redis.conf | awk '{print $2}')" ping

# 确认配置真的加载了
docker exec redis redis-cli --no-auth-warning -a '密码' CONFIG GET appendonly
docker exec redis redis-cli --no-auth-warning -a '密码' CONFIG GET maxmemory

# 确认持久化文件
ls -lh /data/redis/data

CONFIG GET appendonly 返回 yes，/data/redis/data 下能看到 dump.rdb 或 appendonlydir，才说明配置生效、持久化在工作。

六、持久化和备份

Redis 有两种持久化：

生产环境一般两个都开：AOF 保证少丢，RDB 方便搬走做备份。

备份：

# 触发一次快照，然后复制文件
docker exec redis redis-cli --no-auth-warning -a '密码' BGSAVE
sleep 2
docker exec redis redis-cli --no-auth-warning -a '密码' LASTSAVE
sudo cp /data/redis/data/dump.rdb /backup/redis-$(date +%F).rdb

BGSAVE 是异步的，复制前用 LASTSAVE 确认时间戳已经更新。

不落盘直接拉一份也可以，适合数据量不大的场景：

docker exec redis redis-cli --no-auth-warning -a '密码' --rdb /tmp/backup.rdb
docker cp redis:/tmp/backup.rdb ./backup.rdb

恢复就是把 dump.rdb 放回 /data，重启容器。注意恢复前先停 Redis，否则可能被正在运行的实例覆盖。

七、常见报错

八、几条限制

• 单机 Redis 没有高可用，主库挂了就是不可用。要主从或哨兵，是另一套部署，别指望 restart: always 顶上。
• maxmemory-policy allkeys-lru 会淘汰任何键，包括没设过期时间的。做缓存可以，当存储用要换成 noeviction 并密切盯内存。
• appendfsync everysec 是性能和数据安全之间的折中，要求零丢失得用 always，代价是每次写都等磁盘。

访问控制上还有一条：-p 6379:6379 会把 Redis 直接暴露到宿主机所有网卡。只给内网用的服务，端口映射写成 -p 127.0.0.1:6379:6379，让外面连不进来。

一、镜像和目录

用官方镜像，版本写死到小版本：

docker pull nginx:1.27

目录先建出来：

sudo mkdir -p /data/nginx/{conf.d,html,certs,logs}

二、先用 docker run 起一个

docker run -d --name nginx \
  -p 80:80 -p 443:443 \
  -v /data/nginx/conf.d:/etc/nginx/conf.d:ro \
  -v /data/nginx/html:/usr/share/nginx/html:ro \
  -v /data/nginx/certs:/etc/nginx/certs:ro \
  -v /data/nginx/logs:/var/log/nginx \
  -e TZ=Asia/Shanghai \
  --restart=always \
  nginx:1.27

conf.d、html、certs 都是只读挂载，容器不需要往里写东西。logs 必须可写。

跑起来先看默认页：

curl -I http://127.0.0.1/
docker exec nginx nginx -t

nginx -t 返回 syntax is ok 和 test is successful 两行才算配置能过，这个检查在改完配置后每次都要跑。

三、反向代理

在 /data/nginx/conf.d/app.conf 里写一个最简的反代：

upstream app_backend {
    server app:8080;
}

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

    client_max_body_size 50m;

    location / {
        proxy_pass http://app_backend;
        proxy_http_version 1.1;
        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;
        proxy_read_timeout 60s;
    }
}

两个地方容易忽略：

1. upstream 里写的 app 是容器名。Docker 内置 DNS 只在同一个自定义网络里解析容器名，Nginx 容器和 app 容器必须挂在同一个网络上，否则启动时报 host not found in upstream "app"，整个 Nginx 起不来。
2. proxy_set_header Host $host 不能省。默认透传的是 $proxy_host，也就是 upstream 名字，后端按 Host 做的域名路由、重定向、Cookie 域都会错。

改完配置，不用重启容器：

docker exec nginx nginx -t
docker exec nginx nginx -s reload

nginx -s reload 是给 master 进程发 HUP，平滑加载新配置，旧连接不断。先 -t 再 reload，配置写错时 -t 会拦下来，reload 不会让服务挂掉。

HTTPS 站点在同一个 server 块里加：

    listen 443 ssl;
    http2 on;
    ssl_certificate     /etc/nginx/certs/app.example.com.pem;
    ssl_certificate_key /etc/nginx/certs/app.example.com.key;
    ssl_protocols TLSv1.2 TLSv1.3;

证书文件放在 /data/nginx/certs 下，容器里按挂载路径引用。

静态文件单独放一个 server

server {
    listen 80;
    server_name static.example.com;
    root /usr/share/nginx/html;
    index index.html;

    location /assets/ {
        expires 7d;
        add_header Cache-Control "public";
    }
}

四、用 compose 管起来

/data/nginx/docker-compose.yml：

services:
  nginx:
    image: nginx:1.27
    container_name: nginx
    restart: always
    ports:
      - "80:80"
      - "443:443"
    environment:
      TZ: Asia/Shanghai
    volumes:
      - /data/nginx/conf.d:/etc/nginx/conf.d:ro
      - /data/nginx/html:/usr/share/nginx/html:ro
      - /data/nginx/certs:/etc/nginx/certs:ro
      - /data/nginx/logs:/var/log/nginx

networks:
  default:
    name: web
    external: true

业务容器加入这个网络，就能用容器名互相访问：

docker network create web            # 只需建一次
docker network connect web app

用 compose 的话，在业务侧 compose 文件的网络段里写：

networks:
  default:
    name: web
    external: true

这样两边在同一个网络里，proxy_pass http://app:8080 才能解析。

五、日志

官方镜像里 /var/log/nginx/access.log 和 error.log 是指向 /dev/stdout、/dev/stderr 的软链，所以默认 docker logs nginx 能看到访问日志。一旦把宿主机目录挂到 /var/log/nginx，这两个软链被盖住，日志变成宿主机上的真实文件，docker logs 就空了。这不是故障，是挂载导致的必然结果。

用哪种方式，提前定：

挂目录的情况下，加一份 logrotate：

/data/nginx/logs/*.log {
    daily
    rotate 14
    compress
    missingok
    notifempty
    copytruncate
}

copytruncate 是因为容器里的 Nginx 不会收到 logrotate 的 USR1 信号，只能先复制再清空原文件。

要 JSON 格式日志，在 nginx.conf 里定义 log_format；conf.d 里的站点文件只能引用，不能定义全局 format，所以需要挂整个 nginx.conf，或者用 include 拆出来。

六、常见报错

七、备份和升级

Nginx 本身没有"数据"，要备份的只有配置和证书：

sudo tar -czf /backup/nginx-$(date +%F).tar.gz -C /data nginx

升级镜像就是改 image: nginx:1.27 里的小版本，然后：

docker compose pull nginx
docker compose up -d nginx
docker exec nginx nginx -t

容器重建不影响挂载的配置和日志。升级前先备份配置，nginx -t 过了再放流量。

最后一条限制：client_max_body_size、proxy_read_timeout 这类参数没有全局最优值，得按实际业务的上传大小和后端耗时定，默认值在文件上传和大报表导出场景下基本都要调。

一、先把三个"源"分开

装 Docker 遇到的慢和失败，大部分是把三个不同的东西混成一件事了。

这三个不能互相替代。把软件源换成清华，docker pull 该慢还是慢；配了镜像加速器，yum install docker-ce 也不会快一点。离线环境里三个概念同时存在，更容易搞混。

二、在线安装

在线安装就一个变量：包从哪下载。Docker 官方源在国内时好时坏，几个国内镜像站都有完整镜像，把 repo 地址和 GPG 公钥一起换掉就行。

2.1 Ubuntu / Debian

# 1. 依赖
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg lsb-release

# 2. GPG 公钥（注意 keyring 目录和 signed-by 写法）
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://mirrors.tuna.tsinghua.edu.cn/docker-ce/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# 3. 软件源
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.asc] \
https://mirrors.tuna.tsinghua.edu.cn/docker-ce/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 4. 安装
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

有三处容易错：

1. 公钥和 repo 要来自同一个镜像站。混着用一般也能装上，但镜像站换签名的时候，先坏的往往是这种组合。
2. signed-by 是现在推荐的写法，apt-key add 已经废弃了。还在用旧写法的话会看到 Key is stored in legacy trusted.gpg keyring 的警告。
3. VERSION_CODENAME 不能是空的。有些国产衍生系统在 /etc/os-release 里没这个字段，照抄会生成一行缺代号的源，apt-get update 直接报 Malformed entry。这种情况手动填 jammy、focal、bookworm 这种代号。

2.2 RHEL / CentOS / openEuler

# 1. 依赖与仓库管理插件
sudo yum install -y ca-certificates curl gnupg2 yum-utils

# 2. 拉取 repo 文件
sudo curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo \
  -o /etc/yum.repos.d/docker-ce.repo

# 3. 镜像站的 repo 文件可能还指向官方地址，统一替换一次（已经是镜像地址就是空操作）
sudo sed -i 's|https://download.docker.com|https://mirrors.aliyun.com/docker-ce|g' \
  /etc/yum.repos.d/docker-ce.repo

# 4. 安装
sudo yum install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

docker-ce.repo 里是用 $releasever 拼路径的，比如 .../linux/centos/7/x86_64/stable。这个变量 yum 会按系统版本算，CentOS 7/8 算出来正好是 7/8，对得上仓库目录。系统版本比仓库覆盖范围新的时候，问题就来了。

2.3 openEuler 上的 $releasever

openEuler 22.03 算出来是 22，24.03 是 24。而 Docker 仓库只有 centos7、centos8、centos9 三个目录，没有 centos22、centos24，yum makecache 直接 404。

脚本里是按主版本号映射的：

map_docker_releasever() {
    local major
    major="$(printf '%s' "$OS_VERSION" | tr -d '\r')"
    major="${major%%.*}"
    major="${major%%-*}"
    if [[ "$major" =~ ^[0-9]+$ ]] && (( major >= 24 )); then
        DOCKER_YUM_RELEASEVER=9
    else
        DOCKER_YUM_RELEASEVER=8
    fi
}

# 之后在 repo 文件里做定点替换
sed -i "s|\$releasever|${DOCKER_YUM_RELEASEVER}|g" "$repo_file"

24 及以上走 centos9，其余走 centos8。这么做的理由不是版本号刚好对得上，而是 ABI 能兼容：centos8、centos9 的包分别按 RHEL 8、RHEL 9 的 glibc 编，openEuler 22.03 / 24.03 自带的 glibc 比这两个基线新，低版本编出来的二进制在新环境里能跑。映射只是让仓库路径对得上，装完还是 openEuler 系统。麒麟、UOS、OpenCloudOS、Anolis 这些 RHEL 系衍生版同理，脚本里列了名单：

case "$OS" in
    opencloudos|anolis|openanolis|alinux|tencentos|kylin|uos|uniontech)
        PKG_FAMILY="rhel"
        map_docker_releasever
        ;;
    centos|rhel|fedora|rocky|almalinux|ol|amzn)
        PKG_FAMILY="rhel"
        ;;
esac

第一个分支做映射，第二个分支保持 $releasever 原样，因为 CentOS/RHEL/Rocky 的版本号本来就对得上仓库目录。

2.4 脚本怎么选源

脚本内置了三个源，GPG 地址和包地址成对存：

declare -A MIRRORS=(
    [official]="https://download.docker.com|https://download.docker.com"
    [tsinghua]="https://mirrors.tuna.tsinghua.edu.cn/docker-ce|https://mirrors.tuna.tsinghua.edu.cn/docker-ce"
    [aliyun]="https://mirrors.aliyun.com/docker-ce|https://mirrors.aliyun.com/docker-ce"
)

auto 模式只判断官方域通不通，不测速：

if curl -fsSL --connect-timeout 5 --max-time 10 \
    "https://download.docker.com/linux/ubuntu/gpg" -o /dev/null 2>/dev/null; then
    MIRROR_NAME="official"
else
    MIRROR_NAME="aliyun"
fi

两点说明：

1. 探测地址写死成 /linux/ubuntu/gpg 了，跟实际发行版无关，就是看看 download.docker.com 这个域能不能连上，后面不会拿它当下载地址。
2. 通不等于快。5 秒连接超时、10 秒总超时只能筛掉完全连不上的。官方域返回 200 但只有几十 KB/s 的时候，脚本还是选 official。对速度有要求的直接 --mirror aliyun 或 --mirror tsinghua，跳过探测。

用法：

sudo bash install-docker.sh                      # 自动选源
sudo bash install-docker.sh --mirror tsinghua    # 指定源
sudo bash install-docker.sh --mirror official    # 走官方源

脚本跑下来是这么个流程：查 root，看有没有装过 Docker 并提示覆盖，读 /etc/os-release 认发行版和包管理器，选源，卸旧包，装依赖，写 repo 和 GPG，装五个包，systemctl enable --now docker，最后校验一遍。

2.5 装完检查

docker version
docker compose version
systemctl status docker
docker run --rm hello-world

docker compose version 挂了但 docker version 正常，就是 compose 插件没装上。Compose V2 是 CLI 插件，docker compose 这个子命令只认两个目录：

• /usr/libexec/docker/cli-plugins/（系统级）
• ~/.docker/cli-plugins/（用户级）

把二进制放到 /usr/bin/docker-compose，只是多了一个 docker-compose 命令，docker compose 照样报 docker: 'compose' is not a docker command。脚本装的是 docker-compose-plugin 包，插件会进系统插件目录。

非 root 用户要用的话，加进 docker 组再重新登录：

sudo usermod -aG docker <用户名>
# 组变更只对新的登录会话生效，当前 shell 不会变
groups

三、镜像源配置

3.1 registry-mirrors 只管 Docker Hub

镜像加速器的原理不复杂：dockerd 收到 docker pull，如果镜像是 docker.io 的，就按顺序去 mirrors 里试，全失败了才回源。所以要同时满足两个条件：

1. 请求得指向 docker.io。不写域名的短名（nginx、redis:7）会补全成 docker.io/library/nginx:latest，走 mirror；写了别的仓库地址的（harbor.example.com/prod/app:v1）不走 mirror，直接连那个仓库。
2. mirror 本身得能通。2024 年年中开始，一批公共镜像加速服务陆续停了，有的云厂商改成账号绑定专属地址。网上那些"可用加速器列表"时效性都很差，用之前自己测一下。

怎么测：/v2/ 是 Registry V2 的探测端点，返回 200 或 401 都说明服务在线。

for u in https://mirror-a.example.com https://mirror-b.example.com; do
  printf '%-40s %s\n' "$u" "$(curl -s -o /dev/null -w '%{http_code} %{time_total}s' --max-time 5 "$u/v2/")"
done

3.2 写 daemon.json

配置文件在 /etc/docker/daemon.json，没有就新建。只配加速器的最小版本：

{
  "registry-mirrors": ["https://<加速器地址>"]
}

实际环境一般一次把日志、数据目录、cgroup 驱动一起定下来，省得以后反复重启：

{
  "registry-mirrors": ["https://<加速器地址>"],
  "insecure-registries": ["harbor.example.com:80"],
  "data-root": "/data/docker",
  "exec-opts": ["native.cgroupdriver=systemd"],
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "3"
  },
  "live-restore": true
}

log-opts 的值必须是字符串。写成数字 100，dockerd 直接起不来，报错是 JSON 反序列化：

json: cannot unmarshal number into Go struct field ...log-opts of type string

journalctl -u docker -n 50 能看到完整字段名，按提示改成 "100m" 就行。

默认的 json-file 不限制大小，服务容器跑久了能把分区写满。离线安装脚本在 daemon.json 不存在时，写的就是带轮转的一份：

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "3"
  }
}

单容器最多 300 MB（100m × 3），一般 Web 服务够用了；日志量大的在 docker run 或 compose 里单独覆盖 logging 段。

3.3 生效和检查

sudo systemctl daemon-reload     # 只改单元文件时才需要；只改 daemon.json 可以跳过
sudo systemctl restart docker

docker info | grep -A5 "Registry Mirrors"
docker info | grep -E "Docker Root Dir|Cgroup Driver|Storage Driver"

docker info 里看不到 Registry Mirrors，要么 daemon.json 没读到，要么文件位置不对。语法错的话 dockerd 会直接起不来，不会悄悄忽略。systemctl cat docker.service 能看出来 ExecStart 有没有带 --config-file 这种非默认路径。

3.4 私有仓库：HTTP 和自签证书

insecure-registries 管两种情况：仓库是 HTTP 的，仓库用自签证书的。配了之后拉取走明文或者不校验证书，只能在内网用。

HTTPS + 私有 CA 的话，规范做法是把 CA 放到按域名命名的目录：

sudo mkdir -p /etc/docker/certs.d/harbor.example.com
sudo cp internal-ca.crt /etc/docker/certs.d/harbor.example.com/ca.crt
sudo systemctl restart docker

目录名要和 docker pull 里的主机名一字不差，带端口就一起带上，否则证书加载不上，报 x509: certificate signed by unknown authority。

3.5 镜像源相关报错

四、离线安装

4.1 两条路

静态包用得最多，因为目标机经常和打包机不是一个系统，静态包只依赖内核、glibc 和少量系统库。脚本两种都支持，默认走静态。

4.2 打包机：做离线包

找一台有外网、有 DNS 的 Linux 执行：

bash pack-docker-offline.sh --arch x86_64 --mirror aliyun

可选参数：

bash pack-docker-offline.sh --mode rpm      # 在同类 RHEL 系机器上打本地包
bash pack-docker-offline.sh --mode deb      # 在同类 Debian 系机器上打本地包
bash pack-docker-offline.sh --with-images nginx:1.27,redis:7   # 顺带导出镜像
bash pack-docker-offline.sh --docker-ver 27.3.1 --out /data/pkg

打包脚本干了这几件事：

1. 看镜像站上最新的静态包版本。解析目录页 HTML，把 docker-x.y.z.tgz 挑出来按版本排序取最大；探测失败就用脚本里的固定版本。

html="$(mktemp)"
if curl -fsSL --connect-timeout 10 --max-time 30 "$STATIC_BASE/" -o "$html" 2>/dev/null; then
    latest="$(grep -oE 'docker-[0-9]+\.[0-9]+\.[0-9]+(-[0-9]+)?\.tgz' "$html" \
      | grep -v rootless | sort -V | tail -1 || true)"
fi

2. 下载静态包，在打包机上就解开。这一步是故意的：目标机可能没有 tar，解压放打包机做，目标机只管拷文件。

tar -xzf "$tgz_path" -C "$unpack"
cp -a "$unpack/docker/." "$PAYLOAD_DIR/bin/"

3. 下载 docker compose 和 docker buildx 两个插件。这俩只在 GitHub Releases 提供，脚本按官方、mirror.ghproxy.com、ghfast.top 的顺序试，都失败就跳过，安装时会告警，不影响 Docker 本体。

4. 生成三种形态的产物：

docker-offline-x86_64-20261029/
├── install-docker-offline.sh    # 目标机执行
├── VERSION.txt                  # 架构、模式、源、版本、打包时间
├── payload/
│   ├── bin/                     # 已解压的 docker/containerd/runc 等
│   ├── docker-compose
│   ├── docker-buildx
│   └── docker.service
├── packages/                    # rpm/deb 模式下的本地包，静态模式为空
└── images/                      # --with-images 导出的镜像 tar

同时产出同名 .tar.gz 和 .zip。打包机没有 tar 就只出 zip；zip 优先用系统 zip 命令，没有就用 Python 的 zipfile，保证产物总能出来。

4.3 目标机：安装

整目录拷，别只拷脚本：

scp -r docker-offline-x86_64-20261029 root@目标机:/root/

在目标机上执行：

cd /root/docker-offline-x86_64-20261029
sudo bash install-docker-offline.sh

脚本必须和 payload 在同一层，它按固定顺序找 dockerd，命中第一个就返回：

for d in "$PAYLOAD_DIR/bin" "$BUNDLE_DIR/bin" "$BUNDLE_DIR/docker" "$PAYLOAD_DIR/docker" "$BUNDLE_DIR"; do
    if [[ -x "$d/dockerd" ]]; then
        echo "$d"
        return 0
    fi
done

都没找到，才去搜 docker-*.tgz（只看两层深，排除 rootless 包），找到就在目标机现场解。

把脚本单独拷到 /root 再执行的话，$BUNDLE_DIR 就成了 /root，找不到 payload，直接退出，提示"请把完整离线目录拷到服务器后再执行"。

安装过程：

1. 先看 iptables 或 nft 在不在。都没有只告警，静态包里不带这两个工具，容器网络会用不了，得另外离线装。
2. 加载 overlay、br_netfilter 模块，打开 net.ipv4.ip_forward。overlay 是 overlay2 存储驱动的前提，br_netfilter 让桥接流量走 netfilter，缺哪个都不行，轻则容器上不了网，重则 dockerd 起不来。
3. 按包类型装：有 rpm 用 yum localinstall，有 deb 用 dpkg -i，都没有就装静态二进制到 /usr/bin。
4. 装 CLI 插件到 /usr/libexec/docker/cli-plugins/。
5. 写 systemd 单元。离线包里自带一份（payload/docker.service），没有就用脚本内置的：

[Unit]
Description=Docker Application Container Engine
Documentation=https://docs.docker.com
After=network-online.target firewalld.service
Wants=network-online.target

[Service]
Type=notify
ExecStart=/usr/bin/dockerd --host=unix:///var/run/docker.sock
ExecReload=/bin/kill -s HUP $MAINPID
TimeoutStartSec=0
RestartSec=2
Restart=always
StartLimitBurst=3
StartLimitInterval=60s
LimitNOFILE=infinity
LimitNPROC=infinity
LimitCORE=infinity
TasksMax=infinity
Delegate=yes
KillMode=process
OOMScoreAdjust=-500

[Install]
WantedBy=multi-user.target

Type=notify 是让 dockerd 通过 sd_notify 报就绪，静态包里的 dockerd 支持这套协议；LimitNOFILE=infinity 和 TasksMax=infinity 在容器多的时候是必需的，默认 1024 的文件描述符上限，表现出来就是容器随机启动失败。ExecStart 里已经有 --host，所以 daemon.json 里不能再写 hosts，写了就报重复配置：

unable to configure the Docker daemon with file /etc/docker/daemon.json:
the following directives are specified both as a flag and in the configuration file: hosts

6. daemon-reload、enable、restart，然后校验状态，输出 docker version、docker compose version、docker buildx version。
7. images/ 下有 tar 就逐个 docker load。

4.4 目标机没有 tar

三种办法，按可靠程度排：

A. 拷已解压目录（最稳）。打包机上目录本来就是展开状态，scp -r 整个目录过去，目标机不需要任何解压工具。

B. 拷 zip，用 Python 解压。Python 通常随系统预装：

python3 -c "import zipfile; zipfile.ZipFile('docker-offline-x86_64-20261029.zip').extractall()"
cd docker-offline-x86_64-20261029
sudo bash install-docker-offline.sh

C. 拷了 tar.gz，目标机也有 tar：

tar -xzf docker-offline-x86_64-20261029.tar.gz

脚本内部还有一层解压兜底：tar → busybox tar → python3/python 的 tarfile，给包里还带 .tgz 的情况用。三个都没有就停下来，提示去打包机解压后整目录拷，别在目标机上硬解。

4.5 镜像一起搬

装好 Docker 只是解决了运行时，镜像是另一回事。打包这边：

bash pack-docker-offline.sh --with-images nginx:1.27,redis:7

脚本对每个镜像 docker pull 完再 docker save，文件名把 / 和 : 换成 _：

docker save -o "$IMAGES_DIR/${safe}.tar" "$name"

安装那边自动导入：

for img in "$IMAGES_DIR"/*.tar; do
    docker load -i "$img"
done

docker load 会把标签一起恢复，不用重新打 tag。镜像大的话注意 images/ 的体积，docker save 出来是不压缩的层数据，几个 GB 很常见。

离线环境还有条硬规矩：别执行 docker run hello-world。本地没有这个镜像就会去 Docker Hub 拉，没 DNS 或者禁了外网必然失败，报 lookup registry-1.docker.io: no such host，这跟装没装成没关系，很容易看错。验证就用：

docker version
docker compose version
systemctl status docker
docker images

4.6 离线环境的"镜像源"

完全断网又没有内网仓库的时候，镜像只能靠 docker save / docker load 搬，registry-mirrors 没意义，配了只会让失败来得更慢：dockerd 还是会先试镜像站，超时才报错。

接了内网 Harbor 之后，Harbor 就顶了"镜像源"的位置：

• Harbor 是 HTTP：加 insecure-registries。
• Harbor 是 HTTPS + 自签证书：按 3.4 放 ca.crt。
• 要把上游镜像同步进 Harbor：建远程仓库（proxy cache）或者复制规则，客户端改成 docker pull harbor.example.com/library/nginx:1.27，不再碰 Docker Hub。

registry-mirrors 和 Harbor 是两套机制，前者只能加速 docker.io，没法把 harbor.example.com/... 的拉取转到别处。

五、装完后的统一基线

在线离线都一样，装完建议把下面几项一次配好，后面少折腾。

迁 data-root 的时候，新目录必须是空的，先停服务再搬：

sudo systemctl stop docker
sudo mkdir -p /data/docker
sudo rsync -aHAX --numeric-ids /var/lib/docker/ /data/docker/
# 确认 daemon.json 里已有 "data-root": "/data/docker"
sudo systemctl start docker
docker images        # 原有镜像和容器应该都还在

rsync 的 -aHAX 保留权限、ACL 和扩展属性，overlay2 对这些比较敏感，参数少了可能镜像层校验不过。

六、排障对照表

七、几个限制

• 公共镜像加速器能不能用是变化的，本文不写具体地址，用 3.1 的 /v2/ 脚本自己测。
• 静态二进制绕过了包管理，Docker 升级要重新打一遍包；rpm/deb 那条路才能用包管理器升级。
• docker save 不压缩，搬运前可以自己 gzip，导入时先解压再 docker load -i。
• 离线包里的 docker compose、docker buildx 来自 GitHub Releases，网络受限时可能只拿到 Docker 本体，compose 得单独准备。

先说最有用的一条：把边界写清楚，比把提示词写长有用得多。

我在项目根放了一份规则文件，里面就几条：哪个目录可写、哪些目录只读、哪些文件不许碰。账号表、密钥文件、license 这类，写明了不读、不传、不复述，连列目录时看到这种名字都只报告存在、不把内容带出来。有了这份东西，我不用每次开头都叮嘱一遍"注意别把密码贴出来"，它自己会守住。规则文件里还写了读写边界优先于系统权限这件事，意思是我不去改文件系统 ACL，而是用文档声明约束，改起来轻，也不会把权限搞乱。

第二条，让它自己验证，但要求它把没验证的部分说清楚。

前几天写博客发文那条链路，官方文档站是前端渲染的，抓下来只有个壳。它没照着猜，转身去翻本地的 EMlog 源码，把三件事找到了：接口只认表单编码，JSON 发过去字段全空、报错却只有一句 parameter error；更新文章是整行覆盖，没传的字段会被写成空值；正文存的是原文，渲染发生在读取的时候，所以不该自己先转一遍 HTML。这三个都是文档里不会写、只能读代码知道的。后来写百度推送那个插件也一样，本机没有 PHP 也没有 Docker，几个文件只能人工读一遍加括号配平检查，它就明写着"语法没有机器验证过，装完第一件事是 php -l"。这种坦白比什么都重要——它说测过了，我就真以为测过了。

第三条，纠错一次就固化下来，不要重复纠正。

我让它写过一篇技术文章，第一版腔调太像 AI，我说"偏技术一点"。它把设问句、比喻、第二人称、抒情收尾全去掉，按现象、原因、写法重排，结论后面都挂上源码位置。这条偏好被记进长期记忆里了，之后再写对外文档就是默认这个风格。类似地，运维类对话里我习惯贴终端原文、要整块能直接跑的命令、改配置必须带备份和回滚，这些也都记着，不用重说。用 AI 用得顺不顺，很大一部分差别在这里：它有没有地方存这些约定。

第四条，敏感信息不进对话，截图也算。

这条是我自己犯的。查百度推送接口时我截了后台的图，图里带着准入密钥，它当场提醒我密钥已经进对话了、建议去重置。这事提醒我：以前觉得"我没把密码打字发出去"就算安全，其实一张截图就破了。现在贴报错之前会先扫一眼有没有 token、有没有内网地址。同理，涉及公司环境的运维笔记我不会让它直接发到公网博客上，内网 IP、主机名、项目名这些得先剥掉。

第五条，默认停在可回退的那一步。

发文它默认只落到草稿，前台看不见，我确认过再发布；改线上文章之前先把 ID 和标题报出来对一眼；更新前先从线上把原值读回来再整体提交，防止漏传字段把内容清空。这套习惯不是它自己想的，是我一开始要求"先给我看"，然后固化成了流程。工具愿意多问一句、多留一步，比它跑得快更有价值。

第六条，别让它写它没查到的东西。

这次写这篇稿，我让它顺带提一下 Qoder 最近的活动，附上我的邀请链接。它先去抓活动页，发现页面是前端渲染的，抓到的只有几个内部开关（邀请功能开着、限时折扣没开之类），没有任何活动文案，于是明确说不写具体活动名和奖励，免得配一段编出来的说明。我觉得这个反应是对的——缺信息就直说。后来我把活动页截图贴过去，信息补齐了，它才把内容写进来，同时还是留了一句"以页面当时显示为准"。补信息就照实写，没信息就空着，这个分寸比多写几行重要。

再补一条工具层面的：它能在同一个会话里调数据库、浏览器、知识库这些东西，所以"查一条慢 SQL""验一个接口通不通""把这段结论找出处"不用换窗口。上下文不中断这件事，对复杂任务的影响比模型能力本身还大。

Qoder CN 当期活动

顺手把活动页上那几条抄在这儿，省得别人再去找。都是限时的，具体条件和截止时间以页面显示为准：

• 续费加赠：CN 个人版月付续费、月付升级，或过期后再开通，最高加赠 3000 Qwen Credits。
• 新注册福利：2026 年 9 月 30 日起，首次注册 Qoder CN 的个人用户，登录桌面端完成新手任务可领奶茶免单卡，数量有限先到先得。
• 每日 100 Credits：个人用户每天可以在桌面端内主动领取 100 通用 Credits。
• Qwen3.8-Flash 限免：面向新老个人用户开放，活动期间调用该模型不消耗 Credits，计费系数从 0.1× 降到 0.0×。
• 大使计划：不限背景与地区，申请入选后享全年旗舰版会员、新功能优先内测、官方社群与限定周边。
• 高校计划：大学生 1 个月专业版免费抵扣。

每日领 Credits 和模型限免这两条是实打实能省额度的，长任务多的时候差别挺明显。

最后说下邀请。如果你也想试试，可以从下面这个链接注册，是我的邀请入口。具体能给到什么以页面当时显示为准，活动政策会变，我不替官方承诺：

https://qoder.cn/activities?referral_code=owXz6Y8HsI1q6okjlY5Ttr26l5n7dZCE

上面这些心得，包括这篇稿子本身，都是在这条链路上写完再发到博客的。工具带来的最大变化不是省了几分钟打字，是我可以把"记得提醒我检查"这类事情外包出去，让它替我守着流程。

还没动手就撞上一个拦路的

百度给的接口调用地址长这样：http://data.zz.baidu.com/urls?site=https://www.binliyou.com&token=xxx，里面的 site 是带 www 的。而站点实际用的是裸域，www 根本没做解析，curl 一试就露了：

https://binliyou.com/       200
https://www.binliyou.com/   连不上

麻烦的地方在于，域名不一致时百度不会报错。接口照样返回 200、照样给你 success 字段，只是提交的链接全部落在 not_same_site 数组里，一条都不入队。要是先装上跑一轮，当日配额花了、日志看着还挺正常，回头再查域名就晚了。

所以插件里第一个功能不是推送，是比对：

$want = parse_url($query['site'], PHP_URL_HOST);
if (!$want) {
    $want = $query['site'];
}
$mine = parse_url(BLOG_URL, PHP_URL_HOST);
if ($mine && strcasecmp($want, $mine) !== 0) {
    return sprintf(
        '接口地址里的 site 域名是 %s，站点当前域名是 %s。两者不一致时百度会把链接全部退回 not_same_site，一条都不会入队；请先在资源平台改用站点真实域名的接口地址。',
        $want,
        $mine
    );
}

不一致就在设置页顶上挂黄条，推送按钮点了也不执行。整件事里花的时间最少、价值最大的一处是这里。

接口调用本身没什么花样

POST 纯文本，一行一个 URL，Content-Type: text/plain：

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $body,          // implode("\n", $urls)
    CURLOPT_HTTPHEADER => ['Content-Type: text/plain', 'Expect:'],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10,
    CURLOPT_TIMEOUT => 30,
]);

成功返回 remain（当天剩余配额）、success（成功条数）、not_same_site、not_valid；失败是 4xx 带 error 和 message。两个处理原则：remain <= 0 立刻停止，配额当日有效不累计，继续打只是浪费；接口报错也停止，不要在下一次重试时把同一批反复推。

链接用 EMlog 自己的 Url::log($gid) 生成，这样站点哪天开了伪静态或改了 URL 模式，推出去的地址跟着变，不用插件操心。

EMlog 插件的机制是翻源码确认的

几条硬约定，名字写错一个就加载不上：

• 入口 baidu_push/baidu_push.php，头部注释块是插件元信息（Plugin Name / Version / Description）。
• 配置读写走 Storage::getInstance('baidu_push')，数据落在 storage 表。插件名和键名都限 16 个字符、只能 [\w_]，超了会被静默替换成 DefaultPlugin / DefaultName，这个坑够阴的。
• 设置页文件名必须是 baidu_push_setting.php，里面要有 plugin_setting_view() 和 plugin_setting() 两个函数，路由是 admin/plugin.php?plugin=baidu_push。
• 启用/升级/删除的回调在 baidu_push_callback.php，可选。我用了删除回调，卸载时把配置清掉，因为里面存着百度准入密钥：

function callback_rm()
{
    $storage = Storage::getInstance(BaiduPush::PLUGIN);
    $storage->deleteAllName('YES');
}

后台那条路由过了 loginAuth::checkLogin() 和角色校验，确认只有管理员能进，才敢把密钥存这儿。

定时怎么触发

EMlog 没有常驻进程，"定时"得借外力。三条路：crontab 直接调 php、crontab curl 一个带密钥的 URL、前台访问时顺带触发。

选了第一条为主、第二条为辅。理由是密钥进 URL 就会进 nginx 访问日志，等于天天在日志里写一遍。第三条没做，因为没人访问就永远不跑，跑起来还拖慢那一次请求。

一个文件里分两种入口：

if (PHP_SAPI === 'cli') {
    $_SERVER['REMOTE_ADDR'] = '127.0.0.1';
    $_SERVER['REQUEST_METHOD'] = 'GET';
    $_SERVER['HTTP_USER_AGENT'] = 'emlog-baidu-push-cron';
}

require_once dirname(__DIR__, 2) . '/init.php';
require_once __DIR__ . '/baidu_push_core.php';

// init.php 已经把 Content-Type 设成 text/html，这里必须在其之后覆盖
if (PHP_SAPI !== 'cli') {
    header('Content-Type: text/plain; charset=UTF-8');
}

那个注释是踩出来的：EMlog 的 init.php 第二行就 header('Content-Type: text/html')，你要是引导之前就设自己的头，会被它盖掉。CLI 那几行赋值是给 getIp() / getUA() 用的，虽然它们内部有 isset 兜底不会炸，但补上更干净。

后台那几个按钮限了最多五批（BaiduPush::run($mode, 5)），那是同步请求，让一次点击把全站扫完会把请求挂死。完整推送交给 crontab：

30 8 * * * php /app/emlog/content/plugins/baidu_push/run.php increment >> /var/log/emlog-baidu-push.log 2>&1
0 4 * * 0  php /app/emlog/content/plugins/baidu_push/run.php full      >> /var/log/emlog-baidu-push.log 2>&1

站点在 Docker 里就得走 docker exec <php容器> php ...。

增量为什么扫 date，不挂钩子

本来想在 save_log 钩子上记一笔"这篇待推"，后来改成直接扫数据库：

-- 增量：水位之后发布或更新过的可见文章
SELECT gid, date FROM blog
 WHERE type='blog' AND hide='n' AND checked='y' AND date > <水位>
 ORDER BY date ASC, gid ASC;

-- 全量：按主键游标分批，可断点续推
SELECT gid FROM blog
 WHERE type='blog' AND hide='n' AND checked='y' AND gid > <游标>
 ORDER BY gid ASC LIMIT <批大小>;

关键前提是 EMlog 更新文章时会刷新 blog.date，所以"改过的"和"新增的"都会被这条查询带出来，不需要额外记账。好处是插件在正常请求链路上一点开销都不占——入口文件除了 require_once 什么都不做，不挂任何前台钩子。

草稿和待审核的推不出去，靠 hide='n' AND checked='y' 挡。

人工读代码抓出的一个真 bug

游标推进原来是这么写的，在拼 URL 的循环里顺手往前推：

foreach ($rows as $row) {
    $cursor = $row['gid'];          // 错：还没推就先走了
    $urls[] = Url::log($row['gid']);
}
self::pushBatch($api, $urls, $stat);

这样一批推送失败、百度没收下，游标照样走过了那批 gid，那些链接就永久漏推了，除非手动把游标归零重扫。改成先记在局部变量里，确认这批真送出去了才推进：

$lastGid = $cursor;
foreach ($rows as $row) {
    $urls[] = Url::log($row['gid']);
    $lastGid = $row['gid'];
}
$before = $stat['batches'];
self::pushBatch($api, $urls, $stat);
// 只有这一批真正送出去了才推进游标，失败的那批下次仍会重试
if ($stat['batches'] > $before) {
    $cursor = $lastGid;
}

增量水位同理。这类问题不在任何报错里，跑起来一切正常，只有读代码能看见——写完通读一遍这个动作，值。

并发就一个 flock

$file = sys_get_temp_dir() . '/emlog_baidu_push.lock';
$fp = @fopen($file, 'c');
if (!flock($fp, LOCK_EX | LOCK_NB)) {
    $age = time() - (int)@filemtime($file);
    fclose($fp);
    return $age > self::LOCK_TTL ? self::forceLock($file) : false;
}
@touch($file);

拿不到锁就这次跳过并记录原因，不排队不重试。锁文件超过三十分钟视为异常残留会尝试强制接管，但接管用的还是非阻塞 flock，原来那个进程活着的时候抢不到，所以最坏情况只是多跳过一次，不会出现两个任务同时往百度推。

打包传后台也有坑

后台「安装插件」要求上传 zip，解压前的校验逻辑是这样的：

$r = explode('/', $zip->getNameIndex(0), 2);
$dir = isset($r[0]) ? $r[0] . '/' : '';
// type == 'plugin' 时
$plugin_name = substr($dir, 0, -1);
$re = $zip->getFromName($dir . $plugin_name . '.php');
if (false === $re) {
    return -1;   // 前端提示"插件包格式不正确"
}

它拿 zip 第一个条目的顶层目录名当插件名，再要求那个目录下有同名 php。所以文件平铺在压缩包根目录会直接失败，必须是一层目录包着。

另一个坑在打包工具：Windows PowerShell 5.1 的 Compress-Archive 会把条目名写成反斜杠（baidu_push\baidu_push.php），上面那句 explode('/') 就切不出目录了，报错还只告诉你"格式不正确"。改用 bsdtar：

C:\Windows\System32\tar.exe -a -cf baidu_push.zip baidu_push

打完用 tar -tf 回读确认条目是正斜杠：

baidu_push/
baidu_push/baidu_push.php
baidu_push/baidu_push_core.php
baidu_push/baidu_push_setting.php
baidu_push/baidu_push_callback.php
baidu_push/run.php
baidu_push/README.md

1. 请求体只接受表单编码

现象：POST 一个 JSON 到 ?rest-api=article_post，返回 {"code":1,"msg":"parameter error"}，HTTP 400。

原因：所有入参经 Input::postStrVar() 取值：

public static function postStrVar($var_name, $var_default = '')
{
    $str = filter_input(INPUT_POST, $var_name);
    return $str ? addslashes(trim($str)) : $var_default;
}

filter_input(INPUT_POST, ...) 只解析 application/x-www-form-urlencoded 和 multipart/form-data。JSON 请求体不会进入 $_POST，于是 title、content 全部取到默认空值，触发了发布方法里的这个分支：

if (empty($title) || empty($content)) {
    Output::error('parameter error');
}

错误信息不区分"参数没传"和"参数没被解析"，排查时容易往鉴权方向想。

写法：Content-Type: application/x-www-form-urlencoded。Node 侧 new URLSearchParams() 即可，上传接口例外，用 FormData。

2. article_update 是整行覆盖

现象：只想改标题，结果正文变空；只想换标签，封面丢失。

原因：更新方法组装的 $logData 无条件包含全部字段，updateLog() 把它们逐个拼进 SET 子句：

$logData = [
    'title'   => $title,
    'content' => $content,
    'excerpt' => $excerpt,
    'sortid'  => $sort_id,
    'cover'   => $cover,
    'author'  => $author_uid,
    'date'    => strtotime($post_date ?: date('Y-m-d H:i:s')),
    'hide'    => $draft === 'y' ? 'y' : 'n',
];
$this->Log_Model->updateLog($logData, $id, $author_uid);

没有"字段未传则跳过"的判断。缺省值直接落库：

写法：更新前先读回原记录，与本次要改的字段合并后整体提交。读取接口有两个：

• article_detail：返回 content（Parsedown 渲染后的 HTML）和 content_raw（库中原文）。回填必须用 content_raw，否则一轮编辑之后正文里全是标签。
• draft_detail：只返回 hide='y' 的记录，content 即原文，无需二次判断。

两者的差异还能用来判断文章状态：先查 draft_detail，命中即草稿；未命中再查 article_detail，即为已发布。

let existing, isDraft;
try {
  const d = await apiGet('draft_detail', { id }, { auth: true, soft: true });
  existing = normalizeDraft(d.draft);
  isDraft = true;
} catch {
  const d = await apiGet('article_detail', { id });
  existing = normalizeArticle(d.article);   // 取 content_raw
}
const params = { id, ...existing, ...explicitOverrides };

3. 正文存原文，渲染发生在读取时

保存链路不做任何格式转换，读取时才过 Parsedown：

$this->Parsedown = new Parsedown();
$this->Parsedown->setBreaksEnabled(true);   // 自动换行
...
'log_content' => $this->Parsedown->text($row['content']),
'content_raw' => $row['content'],

由此得出三条约束：

1. 正文直接提交 Markdown。预先转成 HTML 会被再处理一次。
2. setBreaksEnabled(true) 使单个换行输出 <br>。段落分隔必须用空行，不能依赖行尾空格。
3. 后台编辑页由 editormd 渲染源码面板，看到 ##、|、``` 属正常显示，不代表转换失败。

log_model 未调用 setSafeMode，因此原生 HTML 块（<img>、<table>、<details>）原样透传给浏览器。但自带的 include/lib/parsedown.php 没有 hideLines 实现，GitHub 风格的 ||| 折叠语法不会渲染，需要折叠用 <details><summary>。

默认值与开关

签名方式的价值在于密钥不出现在 URL 与访问日志里。前提是本机与服务器时钟差小于 300 秒，否则返回 request expired。

脚本

上述规则封装成单文件 CLI，无 npm 依赖（Node 18+ 自带 fetch/FormData/Blob）：

node emlog.mjs post   --file 文章.md --draft --tags "EMlog,Node.js" --comments
node emlog.mjs show   --id 12          # 回读原文与元信息，校验字段是否丢失
node emlog.mjs update --id 12 --publish
node emlog.mjs upload --file 配图.png  # 返回绝对 URL，直接写入正文

update 不带 --file 时沿用线上正文，只提交显式指定的字段；带 --file 时整体替换。密钥从 ~/secrets/emlog.env 读取，不作为命令行参数传入，且所有输出（含异常堆栈）统一把密钥替换为 ***。

一个限制

REST 接口没有删除文章的方法。验证链路产生的测试稿只能登录后台手动删除，因此测试一律用 --draft（前台不可见），正式内容也先落草稿、确认后再 update --publish。