共计 2397 个字符，预计需要花费 6 分钟才能阅读完成。

简介

Syncthing 是一个开源的文件同步工具，可以在不同设备之间同步文件和文件夹。它使用了点对点的方式进行同步，如果点对点连接成功则不需要通过云服务器中转，因此更加安全和私密。

Syncthing 就好比是 Onedrive，当你指定了同步哪些文件夹，它会定时检测文件夹下的文件是否有增加减少或者修改，如果有修改那么将会点对点同步到另外的客户端，当然这是你在一边配置了分享，另一边配置了同步的情况下。当然，它可以是单向同步，也可以是双向同步的，这取决于你的配置。

在正常情况下安装，你是不需要自己搭建发现服务器和中继服务器的，因为默认使用官方的服务器。，中继服务器（Relay Server）则是一种用于帮助设备之间传输数据的服务器。

但是考虑到玩意文件比较多或者文件比较大，文件同步的实时性要求又比较高，使用自己的服务器将是一个比较好的选择，所以接下来也有相关的教程，不需要则可以忽略。

搭建

1. 客户端搭建

docker run -d \
--name syncthing \
-p 8384:8384 \
-p 22000:22000/tcp \
-p 22000:22000/udp \
-p 21027:21027/udp \
-v /home/docker/sync/:/var/syncthing \
syncthing/syncthing:latest

端口 22000：这是 Syncthing 使用的默认监听端口。它用于设备之间建立连接、进行通信和同步文件。当设备之间需要同步文件时，它们将使用该端口进行通信。

端口 21027：这是用于发现服务的 UDP 广播端口。Syncthing 使用该端口来发现局域网内的其他设备，并建立连接。设备之间通过广播消息来发现彼此，然后使用端口 22000 进行进一步的通信和文件同步。

注意这里需要映射文件夹，看你自己情况，如果你已有需要同步的文件夹，请将该文件夹映射到容器内，否则 syncthing 将无法进行同步。

首次进入会警告设置管理员账号和密码，不设置警告不会消失。

/>

点击设置的图形用户界面设置即可。

/>

同步相关的设置下面再讲，先讲如何搭建发现服务器和中继服务器，如果你不需要可以直接跳过。

2. 发现服务器搭建

发现服务器（Discovery Server）是一种用于帮助设备之间发现彼此并建立连接的服务器。当设备加入 Syncthing 网络时，它会向发现服务器发送请求，以获取其他设备的信息。发现服务器会将设备的信息存储在一个公共数据库中，其他设备在需要连接到新设备时可以通过发现服务器获取到该设备的信息。发现服务器的作用类似于一个中介，帮助设备之间建立连接，但它并不参与实际的文件同步过程。

搭建需要公网，在服务器运行如下命令。

docker run -d \
--name syncthing-discosrv \
-p 8443:8443 \
-v /home/docker/syncthing/discosrv:/var/stdiscosrv \
syncthing/discosrv \
-debug -listen=":8443"

使用 docker logs -f syncthing-discosrv 命令查看日志，获取 device ID。

/>

打开客户端，点击设置，选择连接，输入：

https://公网IP:8443/?id=设备id

/>

保存后，点击设备发现状态会显示如下。

/>

3. 中继服务器搭建

中继服务器（Relay Server）则是一种用于帮助设备之间传输数据的服务器。在某些情况下，设备之间直接进行数据传输可能会受到网络环境的限制，例如设备处于不同的局域网中或者网络防火墙的限制。这时，设备可以通过中继服务器进行数据传输。设备将数据上传到中继服务器，然后其他设备从中继服务器下载数据。中继服务器的作用是帮助设备之间绕过网络限制，实现数据的传输。需要注意的是，中继服务器只在必要时才被使用，大部分情况下设备之间直接进行数据传输。

搭建需要公网，在服务器运行如下命令。

docker run -d \
--name syncthing-relaysrv \
-p 22067:22067 \
-v /home/docker/syncthing/strelaysrv:/var/strelaysrv \
syncthing/relaysrv:latest \
-debug -pools="" -listen=":22067" -status-srv=""

使用 docker logs -f syncthing-relaysrv 命令查看日志，获取 Url。

/>

将 ip 替换为你自己的公网 ip。

tcp://0.0.0.0:22000,quic://0.0.0.0:22000,relay://公网IP:22067/?id=设备id

注意：这里前面的监听 22000 端口是有必要加上的，否则只能通过中继服务器传输数据，而不能点对点直连。（这里是更新的内容，至于下面的图片就懒得更新了，侦听器状态有三条记录就是了）

/>

保存后，点击侦听程序显示如下内容。

/>

到这里搭建发现服务器和中继服务器就完成了，当然，新加入的客户端也要进行同样的操作。

使用

1. 添加设备

当你有两个设备时，如果不进行添加设备是无法进行同步操作的，这个添加设备也相当于是一个授权，是一个相互的操作。

首先查看一台机器的识别码。

/>

复制识别码后，在另一台客户端点击添加远程设备进行添加。

/>

这里同时可以备注设备名，共享和高级可以等会再设置。

/>

然后再回到刚刚那台客户端，同意添加设备。

/>

然后就可以在远程设备处看见连接成功了，并可以看见当前是什么连接类型。

/>

2. 文件同步

先在测试1机器上添加文件夹 /var/syncthing/test1。

/>

此时测试1的机器上，/var/syncthing/test1 目录有4个文件，但此时文件夹还是非共享的。

/>

点击选择，设置共享给测试2机器。

/>

测试2机器将收到共享文件夹的确认信息。

/>

我这里将内容同步到 /var/syncthing/tmp 文件夹。

/>

等待一会，发现文件已经同步好了。

提醒：本文发布于521天前，文中所关联的信息可能已发生改变，请知悉！

/>

共计 4576 个字符，预计需要花费 12 分钟才能阅读完成。

前言

有人问清朝云如何搭建一个这样的博客，今天就抽空写一下使用 docker-compose 搭建个人博客。这需要你有一定的 docker 或 docker-compose 基础，如果你还不了解 compose，那么可以看看这篇文章 容器编排 Docker-compose 详解。

直接使用 docker run 其实也是可以的，如果你实在不想用 compose，那么你可以让 chatgpt 帮你转成 docker run 运行的方式，但其实对于三个或者三个以上的容器，清朝云觉得还是有必要使用 compose，这样方便管理。

一、搭建

1. 拷贝nginx配置文件

使用 nginx 都躲不了修改配置文件，不管是反向代理博客，或者是反向代理其他都需要进行修改配置，那么将 nginx 配置文件映射到宿主机是很有必要的。

# 创建目录
mkdir -p /home/docker/nginx && \
cd /home/docker/nginx && \
mkdir conf.d && \
mkdir html && \
mkdir logs

# 不映射文件启动容器，然后 使用 docker cp 拷贝配置文件
docker run -d --name nginx -p 88:80 nginx && \
docker cp nginx:/etc/nginx/nginx.conf ./ && \
docker cp nginx:/etc/nginx/conf.d/default.conf ./conf.d/ && \
docker cp nginx:/usr/share/nginx/html/index.html ./html/ && \
docker rm -f nginx

2. 启动

在目录下新建 docker-compose.yaml 文件。

version: '3.1'
services:
  nginx:
    image: nginx
    container_name: nginx
    restart: always
    network_mode: "host"
    volumes:
      - /home/docker/nginx/nginx.conf:/etc/nginx/nginx.conf
      - /home/docker/nginx/conf.d:/etc/nginx/conf.d
      - /home/docker/nginx/logs:/var/log/nginx
      - /home/docker/nginx/www:/www
      - /etc/localtime:/etc/localtime:ro
  blog:
    image: wordpress:6.0.3
    container_name: blog
    restart: always
    ports:
      - 30080:80
    environment:
      WORDPRESS_DB_HOST: mysql
      WORDPRESS_DB_USER: root
      WORDPRESS_DB_PASSWORD: admin@123!
      WORDPRESS_DB_NAME: blog
    volumes:
      - /home/docker/blog:/var/www/html
    depends_on:
     - mysql
  mysql:
   image: mysql:8.0.26
   container_name: mysql
   restart: always
   ports:
     - 30001:3306
   environment:
     MYSQL_DATABASE: blog
     MYSQL_ROOT_PASSWORD: admin@123!
   volumes:
     - /home/docker/mysql/data:/var/lib/mysql
     - /home/docker/mysql/init:/docker-entrypoint-initdb.d

注意这里 nginx 容器网络使用的是 host 模式，也就是说宿主机的 80 和 443 端口不能被占用，否则无法启动 nginx，除非修改 nginx 默认端口号。

如果你使用的是云服务器，那么需要防火墙需要放行这两个端口。

然后运行 docker-compose up -d 启动容器。

/>

此时访问 nginx 的 80 端口，还是 nginx 默认的页面，因为还没有配置转发到博客。

3. 修改nginx配置文件

这里分为两种情况，分为是否使用 https，看自己情况进行哪一步操作，server_name 修改为自己的域名。

3.1 仅 http

cat > /home/docker/nginx/conf.d/default.conf <<EOF
server {
    listen 80;
    server_name test.com www.test.com;
    access_log  /var/log/nginx/blog.access.log  main;
    error_log  /var/log/nginx/blog.error.log notice;

    location ~* /xmlrpc.php {
      deny all;
    }

    location / {
      add_header 'Access-Control-Allow-Origin' '*';
      add_header 'Access-Control-Allow-Credentials' 'true';
      add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
      add_header 'Access-Control-Allow-Headers' 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type';
      proxy_set_header X-Real-IP \$remote_addr;
      proxy_set_header Host \$host;
      proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
      proxy_pass http://localhost:30080/;
    }
}
EOF

3.2 配置 https

cat > /home/docker/nginx/conf.d/default.conf <<EOF
server {
    listen       443 ssl;
    listen  [::]:443 ssl;
    server_name test.com www.test.com;
    ssl_certificate  /etc/nginx/conf.d/cert/test.com/test.cer;
    ssl_certificate_key /etc/nginx/conf.d/cert/test.com/test.com.key;
    access_log  /var/log/nginx/blog.access.log  main;
    error_log  /var/log/nginx/blog.error.log notice;

    location ~* /xmlrpc.php {
      deny all;
    }

    location / {
      add_header 'Access-Control-Allow-Origin' '*';
      add_header 'Access-Control-Allow-Credentials' 'true';
      add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
      add_header 'Access-Control-Allow-Headers' 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type';
      add_header Content-Security-Policy upgrade-insecure-requests;
      proxy_set_header X-Real-IP \$remote_addr;
      proxy_set_header Host \$host;
      proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
      proxy_pass http://localhost:30080/;
    }
}
server {
    listen 80;
    server_name test.com www.test.com;
    rewrite ^(.*)$ https://\$host:443\$1 permanent;
}

需要说明的是，配置 https 需要申请 ssl 证书，下载后放在指定位置，然后配置 ssl_certificate 和 ssl_certificate_key。

此外，由于配置了 rewrite，访问 80 端口会强制跳转到 443。

配置完成后需要重启 nginx。

docker restart nginx

二、安装

如果不出意外，你将得到一个这样的页面，此时说明 mysql 还没启动，博客就尝试去连接了。

/>

此时需要重启下博客容器。

docker restart blog

再次访问，即可进入正常安装页面，这里选择简体中文即可。

/>

点击继续后将进入最终的设置，这里没有让我们输入 mysql 的地址和用户等信息是因为我们在启动容器的时候已经指定过了。

/>

至此，博客就已经安装完成了。

/>

页面很简陋，因为这是 wordpress 的默认主题，想要达到自己想要的效果还要对站点进行装修，即配置主题和做相关美化配置。

三、配置

1. 主题配置

这里不是必要的，因为你可能有其他喜欢的主题，我这里仅做一个简单的演示。

首先下载一个免费版本的 corepress 主题，地址：https://github.com/ghboke/CorePressWPTheme/releases/tag/v5.8.8

/>

下载压缩包后，打开 http://ip/wp-admin， 输入管理员账号密码进入后台页面。

点击主题，可以看见这里有很多预设的主题，但都不是我们想要的，需要点击添加新主题，再点击上传主题。

/>

选择刚刚下载的安装包，点击立即安装。

/>

安装后点击启用即可。

/>

再访问首页，发现样式已经变了，但还不是想要的效果。

/>

需要再后台点击主题设置，发现这里有一大堆可以设置的内容，包括网站logo、默认缩略图、备案号等等信息。

这里的配置清朝云就不再啰嗦，需要自己去探索，点击右上角也有主题的详细 配置文档。

/>

值得一提的是，除了主题设置还有两个新手不太清楚的地方，那就是首页提示的配置菜单和小工具。

2. 菜单配置

菜单的配置需要点击外观里面的菜单进行配置，需要先添加一个菜单，并配置菜单名称和显示位置。

/>

创建菜单后可以看见顶部没有了提示，但是也没有菜单选项。

/>

这是因为没有添加菜单项，回到设置将左边的菜单项添加到菜单即可。

/>

保存后将在顶部可以看见菜单选项。

/>

3. 小工具配置

有些朋友可能不清楚文章右侧的内容如果配置，其实这些东西就是 wordpress 的小工具，可以在外面里面的小工具进行配置。

比如，我这里需要添加一个作者模块到首页，那么我点击添加小工具即可。

/>

再次访问首页，发现作者模块的小工具已经显示出来。

/>

写在最后

到此为止，使用 docker-compose 搭建 wordpress 的教程就结束了，剩下的还需要自己去探索。

使用这种方式搭建的好处显而易见，所有数据全部在 /home/docker 目录，迁移的时候将这个目录完整地迁移，创建 docker-compose.yaml 文件后再运行 docker-compose up -d 即可完美运行。

提醒：本文发布于520天前，文中所关联的信息可能已发生改变，请知悉！

共计 576 个字符，预计需要花费 2 分钟才能阅读完成。

很多 pdf 是图片导出 pdf 文件，此时如果想要进行搜索和复制是没有办法的。接下要介绍的是 orrcmypdf 工具，这个工具能即将你的 pdf 变成可搜索可复制的工具。

开源项目地址：https://github.com/ocrmypdf/OCRmyPDF

如果你只是想简单试一下效果，将 test.pdf 修改为你的 pdf 文件名，并放在当前目录下。

# 如果文档是中文
docker run  -it --rm -v $PWD:/app jbarlow83/ocrmypdf -l chi_sim test.pdf test_orc.pdf
# 如果文档全是英文
docker run  -it --rm -v $PWD:/app jbarlow83/ocrmypdf  test.pdf test_orc.pdf
# 如果文档有多种语言，-l 参数后面可以加多种语言
docker run  -it --rm -v $PWD:/app jbarlow83/ocrmypdf -l eng+deu test.pdf test_orc.pdf

运行这个命令，将在本目录下生成一个 test_orc.pdf 文件，那么这个文件就是可以搜索和复制的啦。

目前该工具默认是识别英文，对英文效果会比较好，中文的话复制会有空格，目前还没有解决方案，有兴趣的可以查看下 issue：https://github.com/ocrmypdf/OCRmyPDF/issues/715

提醒：本文发布于519天前，文中所关联的信息可能已发生改变，请知悉！

共计 802 个字符，预计需要花费 3 分钟才能阅读完成。

四种NAT类型

NAT 可以分为四种类型：

1. 完全锥形NAT（Full Cone NAT）

完全锥形NAT最简单，也是最灵活的一种。它会为内部网络中的每个主机分配一个公共IP地址和端口号，并且允许从任何外部网络地址的任何端口与内部主机通信。一旦内部主机首次向外部主机发送数据，完全锥形NAT就会将源IP和端口映射到公共IP和端口，以便外部主机可以回复。

2. 地址限制锥形NAT（Address Restricted Cone NAT）

地址限制锥形NAT在完全锥形NAT的基础上增加了限制。它要求内部主机只能与之前已经与其通信过的外部主机进行通信。也就是说，在内部主机与外部主机建立连接之前，外部主机必须已经向内部主机发送过数据包。

3. 端口限制锥形NAT（Port Restricted Cone NAT）

与地址限制锥形NAT类似，端口限制锥形NAT还要求外部主机使用相同的端口号与内部主机进行通信。也就是说，在内部主机与外部主机建立连接之前，外部主机必须已经向内部主机发送过数据包，并且使用相同的源端口号。

4. 对称型NAT（Symmetric NAT）

对称型NAT是最严格的一种。它会为每个不同的目标IP地址和端口组合分配一个唯一的映射，并且只允许与该目标地址和端口进行通信。这意味着，当内部主机与不同的外部主机进行通信时，对称型NAT会为每个连接创建一个新的映射。因此，对称型NAT会限制内部主机能够与多个外部主机同时建立连接。

关于 P2P，不同 NAT 类型的穿透性。

/>

可以看见只有两种情况无法打通。

如何查看NAT类型

使用工具 pystun 工具即可查看 nat 类型，项目地址：https://github.com/jtriley/pystun。

需要有 python 环境，才能进行安装。

pip install pystun

当然你也可以直接运行 docker 命令进行查看。

docker run -it --rm --network=host smilence86/pystun

提醒：本文发布于519天前，文中所关联的信息可能已发生改变，请知悉！

共计 2846 个字符，预计需要花费 8 分钟才能阅读完成。

了解Derp

在搭建 derp 之前，前提是你应该了解并搭建了 headscale 服务端，否则请先看文章 Docker 搭建 headscale 异地组网完整教程。

已经加入 headscale 的异地组网的客户端可以使用如下命令查看当前的 derp 服务器。

# docker 运行的客户端
docker exec -it tailscaled tailscale netcheck
# 非 docker 运行的客户端
tailscale netcheck

/>

可以看见当前离我最近的 derp 是 tokyo 即东京的节点，那新加入的节点为了保底能够进行网络连接，都会先使用 tokyo 的节点进行连接，如果能够直连再切换成直连。

使用 tailscale status 命令可以查看到当前网络的状态。

# docker 运行的客户端
docker exec -it tailscaled tailscale status
# 非 docker 运行的客户端
tailscale status

/>

从图中可以看见，我目前的客户端 mylinux 与其他有两个客户端能够直连，与一个客户端需要经过中继服务器，使用 ping 命令可以更清晰的看见。

/>

搭建derp

1. 启动derp容器

其实 derp 搭建是有必要的，因为上面的 derp 都是官方的节点，如果遇到高峰期挤占带宽会变得很慢，体验非常差。即使自己搭建的 derp 节点，延迟可能比官方某些节点高，但带宽是自己独享的。

使用如下命令即可搭建 derp 服务器。

docker run -d \
--name derper \
-p 12345:12345 \
-p 3478:3478/udp \
-e DERP_ADDR=:12345 \
-e DERP_DOMAIN=derper.your-domain.com \
-e DERP_VERIFY_CLIENTS=false \
--restart always \
yangchuansheng/derper

derper.your-domain.com 修改为自己的域名。设置环境变量 DERP_VERIFY_CLIENTS 是为了验证域名，这里考虑到有些人不一定需要所以设置为 false，如果真正自己使用还是建议设置为 true。

2. 配置nginx

nginx 创建一个 derp.conf 配置文件，内容如下。

server {
    listen       443 ssl;
    listen  [::]:443 ssl;
    server_name  derper.your-domain.com;
    ssl_certificate  /etc/nginx/conf.d/cert/your-domain.com/your-domain.com.cer;
    ssl_certificate_key /etc/nginx/conf.d/cert/your-domain.com/your-domain.com.key;

    location / {
        proxy_pass http://localhost:12345/;
        proxy_redirect https:// https://;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        add_header Content-Security-Policy upgrade-insecure-requests;
    }
}

server {
    listen 80;
    server_name  derper.your-domain.com;
    rewrite ^(.*)$ https://$host:443$1 permanent;
}

这里清朝云设置了强制跳转 https，如果有需要可以不设置，如果没有域名请不需要配置。

配置修改后，记得重启下 nginx，这里需要使用域名或者 ip + 端口能够访问到 derp 页面。

/>

3. 创建derp.yaml

需要告诉 headscale 服务器我们创建的 derp 节点的地址，否则客户端不知道地址将无法使用。

如果你是按照我之前的教程搭建的 headscale，那么运行如下命令，否则需要自己注意配置文件的位置。

cat << EOF > /home/docker/headscale/config/derp.yaml
regions:
  900:
    regionid: 900
    regioncode: ts
    regionname: Tencent Shanghai
    nodes:
      - name: 900a
        regionid: 900
        hostname: derper.your-domain.com
        # ipv4: ip
        stunport: 3478
        stunonly: false
        derpport: 443
EOF

这里的域名替换为自己的域名，如果没配置域名就使用 ip。另外需要注意的是，如果你使用域名配置了 https，那么这里的 derpport 一般填写 443，否则应该使用上面启动容器时指定的 12345 端口。

记得开放3478端口！！！

清朝云不保证使用 ip 的方式能够成功，因为这个能成是听群友说的。

• regions 是 YAML 中的对象，下面的每一个对象表示一个可用区，每个可用区里面可设置多个 DERP 节点，即 nodes。
• 每个可用区的 regionid 不能重复。
• 每个 node 的 name 不能重复。
• regionname 一般用来描述可用区，regioncode 一般设置成可用区的缩写。
• ipv4 字段不是必须的，如果你的域名可以通过公网解析到你的 DERP 服务器地址，这里可以不填。如果你使用了一个二级域名，而这个域名你并没有在公共 DNS server 中添加相关的解析记录，那么这里就需要指定 IP（前提是你的证书包含了这个二级域名，这个很好支持，搞个泛域名证书就行了）。
• stunonly: false 表示除了使用 STUN 服务，还可以使用 DERP 服务。

4. 修改headscale配置文件

修改 config.yaml 文件，paths 指定 derp.yaml 文件的位置，urls 下面的链接是官方提供的中继服务器，根据自己判断是否需要注释。

# /etc/headscale/config.yaml
derp:
  # xxxx
  urls:
  #  - https://controlplane.tailscale.com/derpmap/default
  paths:
    - /etc/headscale/derp.yaml
  # xxxx
  auto_update_enabled: true
  # xxxx
  update_frequency: 24h

修改文件后记得重启 headscale。

docker restart headscale

验证

再次执行 netcheck 命令，可以看见自己搭建的 derp 节点，如果是使用国内的服务器搭建，那么一般这个服务器是最近的。

/>

一段时间后，中继服务器切换为最近的节点即刚刚搭建的节点。

提醒：本文发布于518天前，文中所关联的信息可能已发生改变，请知悉！

/>

共计 549 个字符，预计需要花费 2 分钟才能阅读完成。

Nas 玩家最烦的就是不能在外面远程家里的机器，如果有云服务器还可以自己搭建内网穿透或者是异地组网，但是没有服务器只能用别人提供的免费服务。

今天偶然间在其他地方看见 ZeroNews，发现上手比较简单，并且可以使用 docker 搭建，然后就折腾了一下。虽然我自己不是很需要这款工具，因为本身服务器就挺多的。

首先需要登录 zeronews，然后创建 token。

/>

再创建 docker-compose 配置文件，用创建好的 token 替换掉对应内容。

services:
  zeronews:
    stdin_open: true
    tty: true
    container_name: zeronews
    network_mode: host
    restart: always
    image: docker.zeronews.cc/zeronews:latest
    command: <<token>> 440

注意这里的 440 是对应区域。

/>

启动容器以后，就可以在页面上看见设备在线了，然后可以创建域名和端口。

/>

ZeroNews 的操作逻辑是先选端口，再通过映射到机器的某个端口，所以还需要先选择端口。

/>

再接下来就是创建应用，这里创建一个应用映射到本地 speedtest 服务。

/>

添加好以后使用域名 + 端口访问，效果如下：

/>

免费版速度一般，但是能用，比如 ssh 和打开一些网页还是可以的。

共计 243 个字符，预计需要花费 1 分钟才能阅读完成。

喜欢 docker run 运行命令的朋友经常会遇到的一件事是，忘记之前环境变量设置的什么密码了。如果这个这个容器是很久之前创建的，并且 linux 历史命令也找不到可能就有点束手无策了。

而 runlike 容器能帮助还原之前运行的 docker run 命令，使用方式如下：

docker run --rm -v /var/run/docker.sock:/var/run/docker.sock assaflavie/runlike -p <<容器名称>>

效果如下：

/>

运行 runlike 的输出会有一些默认选项，忽略即可。

共计 3823 个字符，预计需要花费 10 分钟才能阅读完成。

一、区别与联系

OpenAPI 3.x 规范是从 Swagger 2.x 分支出来的，主要是由 Linux 基金会的 OpenAPI Initiative 进行维护的。Swagger 2.x 规范被 OpenAPI 3.x 取代，OpenAPI 3.0 成为新的 API 规范标准。但Swagger 2.x 规范仍然被广泛使用，例如常见的 @Api​、@ApiOperation​ 等注解都是 Swagger 2.x 的内容。

功能/特性	Swagger 2.x 注解	OpenAPI 3.x 注解
类级别描述	​@Api​	​@Tag​
方法级别描述	​@ApiOperation​	​@Operation​
参数描述	​@ApiParam​	​@Parameter​
响应描述	​@ApiResponse​	​@ApiResponse​
数据模型描述	​@ApiModel​	​@Schema​
数据模型属性描述	​@ApiModelProperty​	​@Schema​
接口返回类型	​@ApiResponse​	​@ApiResponse​
全局参数描述	​@ApiImplicitParam​	不需要使用，参数直接通过 @Parameter​ 注解定义

OpenAPI 3.x

引入依赖:

        <!-- Swagger 相关依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

配置类

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) // 扫描所有 API 接口
                .paths(PathSelectors.any()) // 所有路径都生成文档
                .build();
    }

    // 添加 API 信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xx管理系统接口文档")
                .description("xx管理系统相关接口的文档")
                .termsOfServiceUrl("https://www.qcyqq.com")
                .version("1.0")
                .build();
    }
}

在主程序上添加 @EnableOpenApi​ 注解。（不确定是否需要）

访问 ui 的路径为：/swagger-ui/index.html​，openapi 的 json 格式文档路径：/v3/api-docs​

/>

Swagger2.x

引入依赖：

        <!-- Swagger 相关依赖 -->
        <!-- Swagger UI for API documentation interface -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version> <!-- 选择合适的版本 -->
        </dependency>

        <!-- Swagger UI Starter (提供 Swagger UI 界面) -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

配置类：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) // 扫描所有 API 接口
                .paths(PathSelectors.any()) // 所有路径都生成文档
                .build();
    }

    // 添加 API 信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xx管理系统接口文档")
                .description("xx管理系统相关接口的文档")
                .termsOfServiceUrl("https://www.qcyqq.com")
                .version("1.0")
                .build();
    }
}

访问 ui 的路径为：/swagger-ui.html​

二、Swagger2.x 常用注解

1. @Api

• 用于标记一个类作为 Swagger 的资源类。
• 该注解一般用于 Controller 类上，用来说明该类是提供 RESTful API 的地方。

import io.swagger.annotations.Api;

@Api(tags = "用户管理接口", description = "提供用户相关的 CRUD 操作")
@RestController
@RequestMapping("/users")
public class UserController {
    // API 端点
}

2. @ApiOperation

• 用于标记 Controller 方法，描述该方法的作用。
• value：接口的方法描述。
• notes：对接口方法的详细说明。

import io.swagger.annotations.ApiOperation;

@ApiOperation(value = "获取用户详情", notes = "根据用户 ID 获取用户的详细信息")
@GetMapping("/{id}")
public User getUserById(@PathVariable Long id) {
    return userService.getUserById(id);
}

3. @ApiParam

• 用于标注方法参数，描述该参数的详细信息。
• value：描述参数。
• required：标记该参数是否是必填项。

import io.swagger.annotations.ApiParam;

@GetMapping("/{id}")
public User getUserById(
    @ApiParam(value = "用户ID", required = true) @PathVariable Long id) {
    return userService.getUserById(id);
}

三、集成其他ui

1. bootstrap-ui

集成：

        <!-- Swagger 相关依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

       <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

访问 /doc.html 即可查看。

/>

2. Knife4j

项目地址：https://doc.xiaominfo.com/

knife4j 的前身是 swagger-bootstrap-ui， 而 swagger-bootstrap-ui 是一个纯 swagger-ui 的皮肤项目。后续为了满足需求，不得不编写 java 代码，所以在swagger-bootstrap-ui 的 1.8.5~1.9.6 版本之间，采用的是后端 Java 代码和 UI 都混合在一个 jar 包。

这种方式只需要引入 jar 包即可，但是在微服务架构下显得有些臃肿。因此正式将项目改名 knife4j。（作者希望做成一个为Swagger接口文档服务的通用性解决方案,不仅仅只是专注于前端Ui前端.）

swagger-bootstrap-ui 的所有特性都会集中在 knife4j-spring-ui 包中，后端 java 代码和 ui 包分离为多个模块的 jar 包，以面对在目前微服务架构下，更加方便的使用增强文档注解(使用SpringCloud微服务项目，只需要在网关层集成UI的 jar 包即可，因此分离前后端)

/>

集成：

        <!-- Swagger 相关依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.9</version>
        </dependency>

同样访问 /doc.html 即可。

/>