1. 为什么选择Docker Compose部署Yapi

在团队协作开发中，接口管理工具就像交通枢纽的调度中心，而Yapi就是其中最优秀的调度员之一。我经历过手工部署Yapi的痛苦过程，光是MongoDB的配置就能让人抓狂。直到发现Docker Compose这个神器，部署时间从半天缩短到10分钟，这种效率提升就像从绿皮火车换乘高铁。

传统部署方式有三大痛点：环境依赖复杂（需要单独配置Node.js和MongoDB）、配置易出错（数据库连接参数手动输入容易失误）、难以迁移（换服务器就得重来一遍）。而Docker Compose通过声明式配置把整个部署过程标准化，就像把散装零件打包成乐高积木，随便换台支持Docker的机器都能快速重建。

实测下来，用Compose方案比原始文章的手动操作至少省去80%的配置时间。比如原本需要手动执行的MongoDB账号创建、Yapi配置文件编写等操作，现在只需要一个docker-compose.yml文件就能全自动完成。这对中小团队特别友好，新成员入职时再也不用陪着折腾环境了。

2. 部署前的准备工作

2.1 环境检查清单

在开始之前，我们需要确认基础环境是否就位。就像装修房子得先通水电，部署Yapi也需要这些基础条件：

• Docker环境：推荐使用Docker 20.10+版本。检查命令很简单：

  docker --version
  

  如果显示"command not found"，需要先安装Docker。不同系统的安装方式略有差异，Ubuntu下可以这样：

  sudo apt-get update && sudo apt-get install docker-ce docker-ce-cli containerd.io
  

• Docker Compose：这是今天的核心工具。检查是否安装：

  docker-compose --version
  

  如果没有，可以用这个命令安装：

  sudo curl -L "https://github.com/docker/compose/releases/download/v2.23.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
  sudo chmod +x /usr/local/bin/docker-compose
  

• 资源准备：Yapi对硬件要求不高，但生产环境建议至少：

  • 2核CPU
  • 4GB内存
  • 10GB磁盘空间（主要留给MongoDB）

2.2 网络与端口规划

就像小区要规划好门牌号，我们需要提前确定服务端口：

• 3000端口：Yapi的默认Web端口，如果被占用可以在后续配置中修改
• 27017端口：MongoDB服务端口，建议保持默认
• 防火墙设置：如果是云服务器，记得在安全组放行上述端口

我遇到过好几次部署完无法访问的情况，最后发现都是防火墙没配置。可以用这个命令临时检查端口是否开放：

telnet your_server_ip 3000

3. 编写Docker Compose配置文件

3.1 完整的docker-compose.yml

下面是我在实际项目中验证过的配置方案，直接保存为docker-compose.yml文件即可：

version: '3'
services:
  mongodb:
    image: mongo:4.2.21
    container_name: yapi-mongo
    restart: always
    ports:
      - "27017:27017"
    volumes:
      - ./mongo/data:/data/db
    environment:
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD: example
      MONGO_INITDB_DATABASE: yapi
    command: --auth

  yapi:
    image: jayfong/yapi:latest
    container_name: yapi-web
    depends_on:
      - mongodb
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - ./yapi/config.json:/yapi/config.json
      - ./yapi/log:/yapi/log
    environment:
      YAPI_ADMIN_ACCOUNT: admin@yourdomain.com
      YAPI_ADMIN_PASSWORD: ymfe.org
      YAPI_CLOSE_REGISTER: "true"

这个配置有几个精妙之处：

1. 自动初始化数据库：通过environment变量直接创建了带认证的MongoDB
2. 数据持久化：所有重要数据都通过volumes映射到宿主机
3. 安全设置：关闭了默认的注册功能(YAPI_CLOSE_REGISTER)

3.2 配置文件详解

对于需要深度定制的同学，这里拆解关键配置项：

MongoDB部分：

• volumes映射了数据目录，确保容器重启数据不丢失
• environment中的密码建议修改为更复杂的值
• command: --auth开启了数据库认证，这是很多教程遗漏的安全设置

Yapi部分：

• depends_on确保数据库先启动
• 第二个volume映射了日志目录，方便排查问题
• 环境变量中的管理员账号密码是首次登录用的

如果团队规模较大，可以调整这些参数：

environment:
  YAPI_SERVER_PORT: 3000
  YAPI_NODE_ENV: production
  YAPI_LDAP_LOGIN_ENABLE: "true"  # 启用LDAP集成

4. 一键部署与初始化

4.1 启动服务

万事俱备，现在只需要一行命令：

docker-compose up -d

这个-d参数表示后台运行，去掉它可以看到实时日志输出。

启动过程大概需要1-3分钟，取决于网络速度。可以用这个命令观察进度：

docker-compose logs -f

当看到这样的日志时，说明初始化完成了：

[yapi-server] 初始化管理员账号成功: admin@yourdomain.com

4.2 常见问题排查

我在多个环境部署时遇到过这些问题，分享解决方案：

问题1：MongoDB连接失败

• 检查点：确保mongodb服务先启动成功
• 解决命令：docker-compose restart mongodb

问题2：Yapi无法创建管理员账号

• 原因：通常是因为MongoDB认证未生效
• 解决方案：删除容器重新部署，确保command: --auth生效

问题3：页面访问卡顿

• 可能原因：服务器资源不足
• 检查命令：docker stats查看容器资源占用

5. 生产环境优化建议

5.1 性能调优配置

当团队规模超过20人时，建议做这些优化：

1. MongoDB配置增强：

mongodb:
  environment:
    MONGO_INITDB_ROOT_USERNAME: ${DB_USER}
    MONGO_INITDB_ROOT_PASSWORD: ${DB_PASSWORD}
  ulimits:
    nproc: 65535
    nofile:
      soft: 20000
      hard: 40000

2. Yapi内存限制：

yapi:
  deploy:
    resources:
      limits:
        cpus: '1'
        memory: 2G

5.2 备份与恢复方案

接口数据是团队的核心资产，我设计了这个备份方案：

每日自动备份：

# 备份MongoDB
docker exec yapi-mongo sh -c 'exec mongodump -u root -p example --archive' > yapi-backup-$(date +%Y%m%d).archive

# 备份配置文件
tar czvf yapi-config-$(date +%Y%m%d).tar.gz ./yapi/config.json

恢复数据：

cat backup.archive | docker exec -i yapi-mongo sh -c 'exec mongorestore --archive --username root --password example'

5.3 监控与告警

推荐使用cAdvisor+Prometheus监控容器状态：

monitoring:
  image: google/cadvisor
  ports:
    - "8080:8080"
  volumes:
    - /:/rootfs:ro
    - /var/run:/var/run:rw
    - /sys:/sys:ro
    - /var/lib/docker/:/var/lib/docker:ro

6. 进阶使用技巧

6.1 集成LDAP认证

大团队通常会需要LDAP集成，修改配置如下：

environment:
  YAPI_LDAP_LOGIN_ENABLE: "true"
  YAPI_LDAP_SERVER: "ldap://your.ldap.server"
  YAPI_LDAP_BASE_DN: "ou=people,dc=example,dc=com"
  YAPI_LDAP_BIND_PASSWORD: "password"

6.2 配置HTTPS访问

通过Nginx反向代理实现HTTPS：

server {
    listen 443 ssl;
    server_name yapi.yourdomain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
    }
}

6.3 插件系统开发

Yapi支持自定义插件，开发步骤：

1. 在./yapi目录创建plugins文件夹
2. 编写插件代码（参考官方文档）
3. 修改config.json加载插件：

"plugins": [
    {
        "name": "your-plugin",
        "options": {}
    }
]

7. 团队协作最佳实践

经过多个项目的验证，这些工作流特别高效：

接口变更流程：

1. 开发人员在Yapi创建接口草案
2. 前后端评审后标记为"已定稿"
3. 测试人员基于定稿接口编写自动化用例
4. 任何变更都需要走修订流程

权限管理方案：

• 管理员：负责用户管理和项目配置
• 开发者：可以修改接口文档
• 访客：只读权限

通知机制配置：

"mail": {
    "enable": true,
    "host": "smtp.exmail.qq.com",
    "port": 465,
    "from": "yapi@yourcompany.com",
    "auth": {
        "user": "yapi@yourcompany.com",
        "pass": "yourpassword"
    }
}