![nextcloud0.jpg](/static/img/fe7b2d8d32152d532a59d66f77585e5a.nextcloud0.webp)

> 随着数据安全与隐私保护意识的提升，越来越多的个人和组织选择自建云平台来替代公有云。Nextcloud 作为一款开源的文件同步与协作套件，不仅能实现类似网盘的文件存储与分享，还提供日历、联系人、即时通讯、在线文档编辑等协作功能，具备丰富的扩展生态。
>
> 无论是个人家庭的数据管理，还是团队与企业的文件协作，Nextcloud 都能通过灵活的部署方式（单容器、Docker Compose、内网集成数据库与文档套件）满足不同规模的需求。本文将结合实践，从基础到企业内网场景，介绍 Nextcloud 的快速部署方案与关键配置要点。





# 1. 什么是 Nextcloud

Nextcloud 是一个开源的文件同步与协作平台，支持自建部署，帮助个人与组织在自有基础设施上实现“类似网盘 + 在线协作”的能力。与公有云服务不同，Nextcloud 将数据主权掌握在自己手中，同时提供丰富的应用生态用于团队协作与办公自动化。


适用场景包括：个人与家庭私有云、团队文件协作、跨设备资料同步、知识库与笔记、轻量内网网盘、企业内外部文件交换与审计等。


# 1.1 核心特性概览

- 文件同步与共享：桌面与移动客户端双向同步，链接分享、权限与有效期控制、文件版本与回收站等功能。
- 协作套件：日历（CalDAV）、联系人（CardDAV）、任务、Talk 即时通信与音视频会议、白板、笔记、邮件聚合、活动流等。
- 在线文档：可集成 Collabora Online 或 OnlyOffice 实现在线编辑文档、表格与演示文稿。
- 外部存储与整合：对接 S3、SMB/CIFS、NFS、WebDAV、SFTP 以及对象存储，统一访问与权限控制。
- 安全与隐私：端到端加密（可选）、服务端加密、细粒度权限、审计日志、2FA、多租户、合规模块与 DLP（需相关应用支持）。
- 跨平台客户端：Windows、macOS、Linux、iOS、Android，以及 Web 端访问。

# 1.2 架构与工作原理

- Web 与应用层：Nginx 或 Apache 作为前端，PHP-FPM 运行 Nextcloud 应用逻辑。
- 数据库：MariaDB/MySQL 或 PostgreSQL 存储元数据与应用数据。
- 缓存与锁管理：APCu 用于本地缓存，Redis 提供分布式缓存与事务型文件锁，减少数据库压力并避免“文件被锁定”问题。
- 存储层：本地磁盘、网络存储或对象存储，用于保存实际文件数据与预览缩略图。
- 协议支持：文件访问与同步使用 WebDAV；日历与联系人基于 CalDAV/CardDAV。

# 1.3 部署方式

- 单机部署（入门与小型团队）：一台服务器运行 Web、PHP、数据库与 Redis，架构简单、易维护。
- Docker Compose（流行选择）：将 Web、PHP、数据库、Redis 等组件容器化，便于版本管理与迁移。
- Kubernetes（中大型与高可用）：分离服务角色，搭配对象存储、Ingress 与横向扩展，满足大规模并发与多节点。
- 托管服务或厂商方案：由第三方运营与运维，关注业务即可（需评估数据托管策略与合规要求）。

# 1.4 应用生态与扩展

Nextcloud有强大的拓展能力，可以在应用商店里安装应用并集成到Nextcloud里。这点和Wordpress众多的插件很相像。商店地址为https://apps.nextcloud.com ，对于局域网的部署可以下载安装包在服务器上手动进行安装。对于AI的浪潮，Nextcloud也支持部分AI应用场景， 譬如根据大模型来给照片打标签，人脸识别，语音转文字，根据你的问题提问题（类似RAG），但是我觉得AI这块它做得并不是很好。由于我没有实际使用，也就是有个人感觉。


![nextcloud1.jpg](/static/img/d8d9a341db0c4561aa9f3403378fea52.nextcloud1.webp)

# 2. 快速部署

# 2.1 单容器

适合测试与个人轻量使用，只有一个容器，数据库使用SQLite，数据持久化到卷。直接访问 `http://IP:8080`就可以了。


```yaml
services:
  nextcloud:
    image: nextcloud:latest
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - ./nextcloud_data:/var/www/html
```

# 2.2 Nginx代理HTTPS

如果是云服务器，一般都是使用域名和HTTPS，也就是使用Nginx代理。

我是使用Nginx来代理我所有的应用，统一管理HTTPS的证书。这时候就不需要端口的映射，但需要跟Nginx放到同一个Docker网络中，也就是挂到 `nginx-reverse-proxy` 网络下。

```yaml
services:
  nextcloud:
    container_name: nextcloud
    image: nextcloud:latest
    restart: unless-stopped
    expose:
      - 80
    volumes:
      - ./nextcloud_data:/var/www/html
    networks:
      - nginx-reverse-proxy
      
networks:
  nginx-reverse-proxy:
    external: true
```

容器起来后，检查是否加入到`nginx-reverse-proxy` 网络下。如果没有，则Nginx的配置文件会失败。

```bash
$ docker network inspect nginx-reverse-proxy | grep nextcloud
                "Name": "nextcloud",
```

我的Nginx一直是独立部署的。代理80和443端口，挂载Nginx的配置文件和证书等。配置如下：


```yaml
services:
  nginx:
    image: nginx:latest
    container_name: nginx-reverse-proxy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
      - ./log:/var/log/nginx
      - /etc/letsencrypt/live/zenseek.site/fullchain.pem:/etc/nginx/certs/fullchain.pem:ro
      - /etc/letsencrypt/live/zenseek.site/privkey.pem:/etc/nginx/certs/privkey.pem:ro
      - /etc/localtime:/etc/localtime:ro
    networks:
      - nginx-reverse-proxy
    restart: always

networks:
  nginx-reverse-proxy:
    external: true
```
对于Nextcloud的Nginx配置文件如下：

```bash
server {
    listen 443 ssl;
    server_name nextcloud.zenseek.site;

    # Helpful for large uploads and long operations.
    client_max_body_size 2G;
    proxy_read_timeout 3600;
    proxy_request_buffering off;

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;

    # SSL/TLS Security Settings
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # Enable HSTS
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    location / {
        proxy_pass http://nextcloud:80;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
    }
}
```
这样作为个人或家庭使用已经就足够了。在访问 `https://nextcloud.zenseek.site`的时候，会出现已经使用SQLite的警告。

![nextcloud2.jpg](/static/img/e99b1d9124d810d43a6f51c150f1d38f.nextcloud2.webp)

# 2.3 使用独立数据库

正常情况下Nginx，Nextcloud，database是标配。数据库我可以使用Mysql/MariaDB/PostgreSQL。这里我使用PostgreSQL作为例子。因为应用和数据库分开了，所以应用的容器要等待数据库的容器先起来。应用和数据库在一个容器网络，应用和Nginx在一个容器网络。


```yaml
services:

  nextcloud:
    image: nextcloud:latest
    container_name: nextcloud-app
    restart: always
    depends_on:
      - db
    environment:
      POSTGRES_HOST: db
      POSTGRES_DB: nextcloud
      POSTGRES_USER: nextcloud
      POSTGRES_PASSWORD: nc_pg_pwd
    expose:
      - 80
    volumes:
      - ./nextcloud_data:/var/www/html
    networks:
      - nginx-reverse-proxy
      - nextcloud-net

  db:
    image: postgres:latest
    container_name: nextcloud-db
    restart: always
    environment:
      POSTGRES_DB: nextcloud
      POSTGRES_USER: nextcloud
      POSTGRES_PASSWORD: nc_pg_pwd
    volumes:
      - ./db_data:/var/lib/postgresql/data
    networks:
      - nextcloud-net

networks:
  nginx-reverse-proxy:
    external: true
  nextcloud-net:
    external: true
```

这回再部署就不会有警告的消息。部署成功后，会先设置管理员账户并选择安装应用。

![nextcloud3.jpg](/static/img/ce1b8b6fcd5cd3c17ef3b680428c532a.nextcloud3.webp)

然后可以按需安装额外的应用。

![nextcloud4.jpg](/static/img/f93f4f763280b8b450ea342b751c83da.nextcloud4.webp)


# 3 企业内网部署方案

对于有在线预览和编辑，以及多人协同编辑的场景，就需要部署OnlyOffice或是Collabora。我两个都部署了，OnlyOffice是重资产，资源消耗很大。即使家庭使用，也需要4G以上的内存了，毕竟你不可能就只跑一个Nextcloud。虽然Collabora也很消耗资源，但是比OnlyOffice轻多了。所以这个是部署在内网的服务器上，16G的内存是够用了。

Redis用于文件锁、缓存、会话。它不是用来存储文件本身的数据库，而是负责高频、易并发的“易失性”工作，降低数据库压力并提升响应速度。对于我单节点的部署主要就是使用文件锁。当多人或多个应用同时访问同一文件时，Redis 负责加锁/解锁，避免“File is locked”错误与写入冲突。没有 Redis 时会退回用数据库加锁，性能和稳定性都更差。

企业内网部署的另一大特征是没有域名，只能通过IP和端口来区分应用，且没有互联网连接。

## 3.1 Docker Compose File

组件上多了Redis和Collabora。Redis设置了密码。Collabora设置了允许访问的域名，在我们这就是服务器的IP。都是部署在同一台服务器，所以这个IP是相同的。而Nextcloud和Collabora都是在Nginx后面的。


```yml
services:
  db:
    image: postgres:latest
    container_name: nextcloud-db
    restart: always
    environment:
      POSTGRES_DB: nextcloud
      POSTGRES_USER: nextcloud
      POSTGRES_PASSWORD: KbIrfS28UAmce4
    volumes:
      - ./db_data:/var/lib/postgresql/data
    networks:
      - nextcloud-net

  redis:
    image: redis:latest
    container_name: nextcloud-redis
    restart: always
    command: ["redis-server", "--requirepass", "5DGlpDfc6GIMrj"]
    environment:
      - REDIS_PASSWORD=5DGlpDfc6GIMrj
    volumes:
      - ./redis_data:/data
    networks:
      - nextcloud-net

  nextcloud:
    image: nextcloud:latest
    container_name: nextcloud-app
    restart: always
    depends_on:
      - db
      - redis
    environment:
      POSTGRES_HOST: db
      POSTGRES_DB: nextcloud
      POSTGRES_USER: nextcloud
      POSTGRES_PASSWORD: KbIrfS28UAmce4
      REDIS_HOST: redis
      REDIS_HOST_PASSWORD: 5DGlpDfc6GIMrj
    expose:
      - 80
    volumes:
      - ./nextcloud_data:/var/www/html
    networks:
      - nginx-reverse-proxy
      - nextcloud-net

  collabora:
    image: collabora/code:latest
    container_name: collabora
    restart: always
    environment:
      - domain="10\\.10\\.10\\.10"   # replace with your Nextcloud IP or regex
        # - extra_params="--o:ssl.enable=false"
      - username=admin
      - password=KgJbOStIEQ1urI
    cap_add:
      - MKNOD
    networks:
      - nginx-reverse-proxy
      - nextcloud-net
    expose:
      - 9980   # internal port only; Nginx will handle HTTPS

networks:
  nginx-reverse-proxy:
    external: true
  nextcloud-net:
    external: true
```
## 3.2 Nginx配置文件

Nextcloud的Nginx配置。这里面要把端口带进去，不然Nextcloud PHP生成的连接会将端口剥离。

```bash
server {
    listen 8009 ssl;
    server_name 10.10.10.10;

    ssl_certificate /etc/nginx/certs/10.10.10.10.crt;
    ssl_certificate_key /etc/nginx/certs/10.10.10.10.key;

    # SSL/TLS Security Settings
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # Enable HSTS
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    location / {
        proxy_pass http://nextcloud-app:80/;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Port $server_port;
        proxy_set_header X-Forwarded-Ssl on;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        # To support login forms and large payloads
        # client_max_body_size 128M;
    }
}
```

Collabora的Nginx配置。Collabora默认是使用HTTPS来通讯的，除非在Docker Compose配置里禁用SSL。实际中我试验了禁用SSL，Collabora直接无法访问了。经过多种测试，只有现在的配置好用。我也试验过了OnlyOffice对特殊的端口支持的不好，都会重定向回443端口。所以在内网环境，我放弃了OnlyOffice。

```bash
server {
    listen 8010 ssl;
    server_name 10.10.10.10;

    ssl_certificate /etc/nginx/certs/10.10.10.10.crt;
    ssl_certificate_key /etc/nginx/certs/10.10.10.10.key;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers HIGH:!aNULL:!MD5;

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    # Collabora main endpoint
    location / {
        proxy_pass https://collabora:9980;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Optional, fixes some WebSocket issues
        proxy_read_timeout 36000s;
        proxy_buffering off;
    }

    # WebSocket endpoint (needed for Collabora real-time editing)
    location ~ /lool/(.*)/ws$ {
        proxy_pass https://collabora:9980;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_read_timeout 36000s;
        proxy_buffering off;
    }

    # Optional: prevent large file upload issues
    client_max_body_size 100M;
}
```
## 3.3 Nextcloud PHP文件

如果以为上面就算结束，那你就错了。还需要在Nextcloud的 PHP配置文件增加受信任的域，也就是白名单。对于特殊端口的，还需要设置重写规则。

文件位置在 `./nextcloud_data/config/config.php`。

在里面添加下面的设置，这样在生成其他链接的时候带上端口号。

```bash
  'trusted_domains' => 
  array (
    0 => '10.10.10.10',
  ),
  'overwrite.cli.url' => 'http://10.10.10.10',
  'overwritehost' => '10.10.10.10:8009',
  'overwriteprotocol' => 'https',
```

![nextcloud5.jpg](/static/img/d23a774265767187539e950cc2bfa998.nextcloud5.webp)

不过，受信任域的问题我依然没有解决。依然会有如下的报错。

![nextcloud6.jpg](/static/img/08331e5e098c672fc485ff056e924601.nextcloud6.webp)

## 3.4 集成Collabora到Nextcloud

正常我们直接在应用商店里安装 Nextcloud Office就可以了。但是在局域网没有外网的访问权限，只能下载安装包到本地，在上传到服务器上。下载完的文件是 .tar.gz的格式。将其上传到`./nextcloud_data/custom_apps/` 下，然后解压到成一个文件夹，设置好所有属性，在启用应用。

```bash
tar -zxvf richdocuments-v8.7.4.tar.gz
chown -R www-data:www-data richdocuments

# 进入到容器内部
docker exec -it nextcloud-app /bin/bash

# 在容器内部
php occ app:enable richdocuments

root@417f3965c025:/var/www/html# php /var/www/html/occ app:list | grep rich
  - richdocuments: 8.7.4
```

这时再回到Nextcloud的设置界面，在左侧边栏就多了一个Office的选项。选择使用自己的Collabora服务器，添加Collabora的对外地址。点击保存后就会验证链接是否好用。我这有一个警告，一直没有解决，虽然我设置了受信任域。

![nextcloud7.jpg](/static/img/6debc48da37efd7d1470d42e5d0116e8.nextcloud7.webp)

这样我们就大功告成了，可以在Nextcloud里直接打开并编辑Word, PPT, Excel的文件了。但每次打开文件都会有这个报错，点击一下打开再点别的地方就没有了。


![nextcloud8.jpg](/static/img/fb3ceb2b89b3d47e88ae7186a8b8e317.nextcloud8.webp)

Nextcloud 实战：打造属于你的私有云与在线协作平台

![250823_metabase0.jpg](/static/img/bc2b3ed9ba178173d7e16f0104d3a5ba.250823_metabase0.webp)
> 本文介绍了开源 BI 工具 **Metabase** 的功能特点、优势与不足，并结合实际经验，演示了如何通过 Docker 快速部署测试环境、如何进行数据持久化配置，以及在生产环境下如何结合 PostgreSQL、Nginx 进行高可用、安全的部署。文章还分析了 Metabase 在 CPU、内存、磁盘等资源上的消耗，并给出了官方推荐的硬件配置和部署实践，帮助读者从入门到上线全面掌握 Metabase 的使用



# 1. Metabase介绍
Metabase 是一款非常流行的**开源商业智能（BI）工具**。它的核心设计理念是让数据分析变得简单、快捷。链接到你的数据库，无需任何代码，即使是非技术人员也能够轻松地从数据中获得答案。

## 1.1 核心特点
1. **轻松提问**
    - **为非技术人员设计**：用户无需编写复杂的 SQL 代码，只需通过点击式的图形化界面，选择数据表、筛选条件和汇总方式，就能构建出自己想查询的问题。
    - **为技术人员提供便利**：对于数据分析师或开发者，Metabase 也内置了功能强大的 **SQL 编辑器**，可以直接编写原生 SQL 查询，进行更复杂、更精细的数据分析。
2. **丰富的可视化**
    - 它支持将查询结果快速转换成各种图表，如折线图、柱状图、饼图、地图、漏斗图、数据表格等。
    - 用户可以轻松切换图表类型，找到最适合展示数据的形式。
3. **仪表盘**
    - 用户可以将多个“问题”（即图表）组合到一个仪表盘中，形成一个全面的数据概览。
    - 仪表盘是交互式的，可以添加筛选器（如时间范围、用户类型、国家/地区等）。当筛选器变化时，整个仪表盘的所有图表都会同步更新，非常适合用于业务监控和数据汇报。
4. **数据模型**
	- 管理员可以对数据库的原始表和字段进行“美化”，比如：
        - 将难懂的字段名（如 `auth_user_profiles`）重命名为易于理解的名称（如“用户信息”）。
        - 为字段添加注释说明。
        - 隐藏不需要分析的字段。
	- 可以根据现有的字段，添加新的字段，譬如对字符串的一些操作。
5. **广泛的数据源支持**
	- 关系型数据库：MySQL / MariaDB，SQL Server，PostgreSQL
	- 非关系型数据库：MongoDB

## 1.2 使用优势
- **开源免费**：其社区版是完全开源和免费的，也有付费的企业版，包括一些企业级的特性譬如SSO。
- **极致易用**：用户界面非常直观简洁，上手操作容易，特别适合非技术背景的业务人员。
- **部署快速**：安装和配置过程非常简单，支持容器部署，几分钟内就可以连接到数据库并开始使用。
- **社区活跃**：作为一款热门的开源项目，它拥有一个庞大的全球用户社区，遇到问题时很容易找到解决方案。

## 1.3 功能局限
- **高级可视化能力有限**：与 Tableau 或 Power BI 等企业级付费 BI 工具相比，Metabase 在图表的高度自定义和复杂可视化方面稍显逊色。
- **ETL 功能较弱**：它主要是一个查询和展示工具，对于复杂的数据清洗、转换和整合（ETL）能力较弱。譬如使用Python将原始数据进行清洗和转换并存入到数据库中。
- **超大规模数据性能**：其性能在很大程度上依赖于底层数据库的性能。在处理极大规模数据集时，可能不如一些专门为大数据优化的商业 BI 平台。

# 2. 测试环境部署
老规矩我们还是使用Docker进行部署。

![250823_metabase2.jpg](/static/img/c73285fdec16544a3098546d48f54dec.250823_metabase2.webp)

## 2.1 快速启动（最简单的 Docker 部署）
直接拉取镜像并启动容器。容器默认监听3000端口。启动有点慢，稍等一会儿才能使用。
```bash
docker pull metabase/metabase:latest

docker run -d -p 3000:3000 --name metabase metabase/metabase
```

这个只适用于简单感受下Metabase的使用。最初为了简单我就直接使用的这种方法，但是每次重建容器，所有的配置参数，包括数据库，仪表盘，问题什么的就都没有了。

Metabase内置了H2数据库，它使用底层文件系统存放应用数据。由于我们并没有做数据持久化，所以每次重建容器，数据都会丢失。

## 2.2 数据持久化与专用网络
可以将Metabase的数据和数据库目录进行持久化。我还创建了一个Metabase的网络，将别的应用的数据库也加入到这个网络中。因为一般数据库（容器内）不直接对外访问，通过这个专用网络，Metabase就可以链接到相应的数据库了。

```yaml
services:
  metabase:
    image: metabase/metabase:latest
    container_name: metabase
    hostname: metabase
    volumes:
      - ./metabase/metabase-data:/metabase-data
      - ./metabase/metabase.db:/metabase.db
    restart: always
    ports:
      - "3000:3000"
    networks:
      - metabase_network
        
networks:
  metabase_network:
    driver: bridge
```

## 2.3 资源消耗分析
基于最简单的部署方式，实际的资源消耗如下：

![250823_metabase1.jpg](/static/img/0defd8a372cd864be4ca4420a5ee7856.250823_metabase1.webp)

### 2.3.1 CPU 占用情况
Metabase 只是生成 SQL 并将查询任务发送给数据库。真正的数据计算压力主要在源数据库上
- **查询执行**：当用户运行一个复杂的查询（尤其是有多层聚合和计算的）时，CPU 会短暂飙升。
- **数据同步**：Metabase 会定期扫描您连接的数据库，同步表结构和元数据，这个过程会消耗 CPU。
- **仪表盘渲染**：同时加载一个包含许多图表的复杂仪表盘时，CPU 会有明显占用。
### 2.3.2 - 内存需求
内存是影响 Metabase 性能和稳定性的最重要因素。官方建议至少需要 **2GB RAM** 才能比较流畅地运行。对于生产环境，**4GB RAM** 是一个更安全的起点。
- **运行应用**：Metabase 是一个 Java 应用程序，Java 虚拟机（JVM）本身就需要一定的基础内存来运行。在测试环境下占用了1.1G的内存。
- **处理请求**：每个用户的查询、图表加载和仪表盘刷新都会消耗内存。并发用户越多，内存需求越大。
- **结果缓存**：Metabase 会将查询结果缓存到内存中，以加快后续访问速度。缓存的图表越多、数据量越大，占用的内存就越多。

### 2.3.3 磁盘空间
磁盘空间通常是最不成问题的资源。Metabase不会在自己的服务器上存储业务数据。它只是一个查询和展示工具。磁盘空间的消耗主要包括，应用本身，H2数据库文件（用于存储用户信息、问题、仪表盘、设置等）以及一些日志文件。

# 3. 生产环境部署

官方建议使用单独的关系型数据库来专门作为应用数据库，官方例子都是使用PostgreSQL。
## 3.1 硬件资源推荐
- **Metabase应用服务器**： 起始是1核1G的配置，每多20个并发用户增加1核2G的硬件资源。
- **Metabase应用数据库服务器**：起始是1核2G的配置，以PostgreSQL为例，每多40个并发用户增加1核1G的硬件资源。

## 3.2 官方 Docker Compose 配置

详情见 [Running Metabase on Docker](https://www.metabase.com/docs/latest/installation-and-operation/running-metabase-on-docker)。
```yaml
services:
  metabase:
    image: metabase/metabase:latest
    container_name: metabase
    hostname: metabase
    volumes:
      - /dev/urandom:/dev/random:ro
    ports:
      - 3000:3000
    environment:
      MB_DB_TYPE: postgres
      MB_DB_DBNAME: metabaseappdb
      MB_DB_PORT: 5432
      MB_DB_USER: metabase
      MB_DB_PASS: mysecretpassword
      MB_DB_HOST: postgres
    networks:
      - metanet1
    healthcheck:
      test: curl --fail -I http://localhost:3000/api/health || exit 1
      interval: 15s
      timeout: 5s
      retries: 5
  postgres:
    image: postgres:latest
    container_name: postgres
    hostname: postgres
    environment:
      POSTGRES_USER: metabase
      POSTGRES_DB: metabaseappdb
      POSTGRES_PASSWORD: mysecretpassword
    networks:
      - metanet1
networks:
  metanet1:
    driver: bridge
```

## 3.3 数据库连接池优化
默认Metabase的连接池设置为15个连接。Metabase为每个数据库，包括应用数据库，管理一个这样的连接池。可以通过环境变量`MB_APPLICATION_DB_MAX_CONNECTION_POOL_SIZE`来更改每个连接池的数量。但是要保证有充足的内存，不然Metabase会将连接放进队列，直到有空余的内存。

Metabase建议使用负载均衡器来负载请求到不同的Metabase实例上。

## 3.4 HTTPS 部署方式
如果是直接使用Metabase来作为处理HTTPS流量的话，请参考官方文档[Using HTTPS with Metabase](https://www.metabase.com/docs/latest/configuring-metabase/customizing-jetty-webserver#using-https-with-metabase)。

```bash
export MB_JETTY_SSL="true"
export MB_JETTY_SSL_PORT="8443"
export MB_JETTY_SSL_KEYSTORE="path/to/keystore.jks" # replace this value with your own
export MB_JETTY_SSL_KEYSTORE_PASSWORD="storepass" # replace this value with your own
java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar

```

参考[Java Keytool Essentials: Working with Java Keystores](https://www.digitalocean.com/community/tutorials/java-keytool-essentials-working-with-java-keystores) 来生成Java Keystore。在Metabase容器内部是集成了`keytool`这个工具的。

![250823_metabase4.jpg](/static/img/017c0b4779d74e24e3244990805d6c7f.250823_metabase4.webp)

我是没有使用这个方法的，因为太麻烦了。官方也不推荐这么做，官方推荐使用的是负载均衡器来做TLS终结。

## 3.5 使用 Nginx 作为反向代理

![250823_metabase3.jpg](/static/img/faa8fbada6a681dd234923fd48729070.250823_metabase3.webp)
我还是Nginx来代理Metabase的请求，在内网通过端口来区分服务。一个容器网络连接到Nginx，另一个网络用来放各种数据库，包括Metabase的应用数据库。

完整的Metabase的Docker Compose文件如下：

```yaml
services:
  metabase:
    image: metabase/metabase:latest
    container_name: metabase
    hostname: metabase
    volumes:
      - /dev/urandom:/dev/random:ro
    expose:
      - 3000
    environment:
      MB_DB_TYPE: postgres
      MB_DB_DBNAME: metabaseappdb
      MB_DB_PORT: 5432
      MB_DB_USER: metabase
      MB_DB_PASS: cl52JuiyUSR71kaq
      MB_DB_HOST: postgres
    networks:
      - database-pool
      - nginx-reverse-proxy
    healthcheck:
      test: curl --fail -I http://localhost:3000/api/health || exit 1
      interval: 15s
      timeout: 5s
      retries: 5

  postgres:
    image: postgres:latest
    container_name: postgres
    hostname: postgres
    environment:
      POSTGRES_USER: metabase
      POSTGRES_DB: metabaseappdb
      POSTGRES_PASSWORD: cl52JuiyUSR71kaq
    networks:
      - database-pool

networks:
  database-pool:
     external: true
  nginx-reverse-proxy:
     external: true
```

Nginx的配置文件也很简单。
```bash
server {
    listen 8008 ssl;
    server_name 10.10.10.10;

    ssl_certificate /etc/nginx/certs/int.crt;
    ssl_certificate_key /etc/nginx/certs/int.key;

    location / {
        proxy_pass http://metabase:3000;
        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;
    }
}
```
容器的状态如下
![250823_metabase7.jpg](/static/img/e972a4c550d028e02adf9aa873e569a2.250823_metabase7.webp)

这样我就可以通过`https://10.10.10.10:8008`来访问Metabase了。

![250823_metabase5.jpg](/static/img/da9fed13dac2af72fe6636c913780406.250823_metabase5.webp)

在设置完管理员账户后，需要连接到数据库。当然也可以使用自带的demo的H2数据库来测试一下，稍后再添加生产数据库。

![250823_metabase6.jpg](/static/img/9a566c68236ef974c6c025d6819a29e9.250823_metabase6.webp)

Metabase 部署与实践：从测试环境到生产环境的完整指南

![250812_vaultwarden_mail_setup0.jpg](/static/img/8173180d786722166211fe8bb34e5c00.250812_vaultwarden_mail_setup0.webp)

> 本指南详细介绍了如何在私有环境下部署和配置 Vaultwarden，包括开启并安全访问管理界面、配置 Gmail SMTP 邮箱实现邀请与通知功能、常见排错方法，以及如何新建组织和实现密码条目的共享。通过实际操作与截图讲解，帮助你高效搭建并管理适合家庭和小团队的密码服务系统。


使用Vaultwarden的高级特性需要开启管理界面来设置。Vaultwarden的部署请参考 [Docker部署Vaultwarden](https://www.zenseek.site/post/4) 。



# 一、访问与配置管理后台

假设Vaultwarden的访问地址是https://example.com， 管理界面在访问地址后加/admin。输入Admin_Token来访问管理界面。

## 1.1 生成Admin_Token

现在依然可以使用明文的密码来访问管理界面，但是Vaultwarden建议使用加密的密码来访问。
可以参考官方文档[secure the admin token](https://github.com/dani-garcia/vaultwarden/wiki/Enabling-admin-page#secure-the-admin_token)。其中`vaultwarden`是你容器的名字，输入设置的密码，至少8位，确认密码。最后生成admin token，将其放入到环境变量之中。

```bash
docker exec -it vaultwarden /vaultwarden hash
Generate an Argon2id PHC string using the 'bitwarden' preset:

Password: 
Confirm Password: 

ADMIN_TOKEN='$argon2id$v=19$m=65540,t=3,p=4$LNuRR3K0232FW68U36aFCNsLGB5dmn079GJLFI1M088$NGkD4RrnStvRidXfI71sb7sglCU/ov0oCgpyhWsXyJo'

Generation of the Argon2id PHC string took: 182.049239ms
```

Vaultwarden推荐的方法不会让Admin Token暴露在Docker Compose的环境变量里，密码还是自己设置的密码，但是环境变量使用的是密码的哈希。

# 1.2 管理后台访问排查

但是我也遇到了一些问题，就是无法通过这个新的密码来访问管理界面。这是因为第一次安装Vaultwarden之后，会在容器内生成配置文件，路径是`/data/config.json`。最开始设置的环境变量会被写到这个文件里。只要不删除数据持久卷，每次启动或是重新生成容器都会加载这个配置文件。这个配置文件的优先级比Docker Compose里环境变量的优先级要高。

在这个配置文件内修改参数，然后重启容器重新加载配置，就可以访问后台的管理界面了。除了这个Admin Token外，这个配置文件还包含其他的配置。当我们进入到管理界面后，在管理界面进行的修改并保存后是会写到这个配置文件里的。

# 二、配置邮箱实现邀请与通知

正常我们私有部署的Vaultwarden是给自己或是家人朋友用，并不希望任何人都可以注册和使用。所以一般在注册完自己的管理员账号后，都关闭注册功能。但是如果你希望家人和朋友使用的时候，不可能每次都去管理界面设置。这时候我们可以使用邮件邀请的方式来添加新的用户，这就是需要用到一个邮箱来发送这些邀请邮件。此外，其他的一些功能，譬如重置密码都需要用到邮箱。虽然自己可以搭一个邮箱的服务器，但是并没有太大的必要，除非用户非常多，而且你还有其他的应用也会频繁地用到邮箱服务。所以本着多一事不如少一事的风格，我们就利用已有的邮箱地址。


我们这里只进行邮件的发送而不需要接收邮件，所以只需要设置SMTP。这里我使用我的Gmail来进行设置。

## 2.1 管理后台设置 SMTP

首先使用设置的密文密码来登录管理界面。

![250812_vaultwarden_mail_setup7.jpg](/static/img/3a46aec62e95215eb95673f2224aa784.250812_vaultwarden_mail_setup7.webp)

在设置里找到SMTP。

![250812_vaultwarden_mail_setup9.jpg](/static/img/15349deb7c7bd20cee939c4cfefe260a.250812_vaultwarden_mail_setup9.webp)

点开SMTP设置，你需要准备你的Gmail账号和App Password。

![250812_vaultwarden_mail_setup5.jpg](/static/img/f97479ac5f8c51a26e3aec66800baf1b.250812_vaultwarden_mail_setup5.webp)

这个App Password是给生成的给应用使用的，一般情况下你的谷歌账号都会开启二次认证。而这个App Password则可以直接用于应用访问你的谷歌邮箱。所以谷歌也是不推荐使用这个App Password的。如果是我们自己写的应用，需要调用谷歌邮箱的API，则需要注册你的应用并生成密钥，这里略过不提。如果你在这里使用了你的邮箱登陆密码，则会出现BadCredential的报错。

![250812_vaultwarden_mail_setup1.jpg](/static/img/4786d0ee59754d0c89933029ea0945f2.250812_vaultwarden_mail_setup1.webp)

## 2.2 生成 Gmail App Password

点击[Create and manage your app passwords](https://myaccount.google.com/apppasswords) 链接。

![250812_vaultwarden_mail_setup2.jpg](/static/img/423032e4ca0a1785e00af5fa807bb546.250812_vaultwarden_mail_setup2.webp)

设置APP的名字，再点击生成就出现了16位的APP Password。

![250812_vaultwarden_mail_setup3.jpg](/static/img/cbe68c6cab14801ed5e0afdb4ee90f06.250812_vaultwarden_mail_setup3.webp)

再返回刚才的链接，你也可以选择删除这个APP Password。

## 2.3 测试邮件发送

在SMTP设置的页面上，最后有一个Test SMTP的选项，填入你的其他的邮箱地址，再点击发送。发送成功的通知如下。如果失败则会有相应的报错信息，再进行排错。

![250812_vaultwarden_mail_setup4.jpg](/static/img/ff65393e34e1a6c0c1c8e7f0c05f5b5c.250812_vaultwarden_mail_setup4.webp)

在测试邮箱里会收到如下一封邮件。

![250812_vaultwarden_mail_setup6.jpg](/static/img/78a1eb508e5b66450e75705717059162.250812_vaultwarden_mail_setup6.webp)

## 2.4 查看容器日志排错

有任何报错都在日志里显示出来，成功就会返回200 OK的状态。

```bash
[2025-08-12 06:59:13.534][request][INFO] POST /admin/test/smtp

[2025-08-12 06:59:15.588][vaultwarden::mail][ERROR] SMTP 5xx error: permanent error (535): 5.7.8 Username and Password not accepted. For more information, go to5.7.8  https://support.google.com/mail/?p=BadCredentials d9443c01a7336-241e899a51esm293151375ad.115 - gsmtp - Authentication credentials invalid

[2025-08-12 06:59:15.589][response][INFO] (test_smtp) POST /admin/test/smtp application/json => 400 Bad Request

省略......

[2025-08-12 07:01:19.174][request][INFO] POST /admin/test/smtp

[2025-08-12 07:01:23.312][response][INFO] (test_smtp) POST /admin/test/smtp application/json => 200 OK
```

## 2.5 防火墙放行 SMTP 端口

在配置中我们使用的是587接口，所以我们需要在防火墙里放行587接口。我使用的是腾讯云的轻量服务器，在控制台里选择防火墙，新建规则，然后放行587号端口。

![250812_vaultwarden_mail_setup10.jpg](/static/img/5c480646f6c129d5a3ed16cdc1704a24.250812_vaultwarden_mail_setup10.webp)

因为我的Vaultwarden是在Nginx后面，我还曾想是否会影响到Vaultwarden的邮箱发送，因为Nginx只监听80和443端口。后来证明它属实不影响邮件的发送功能，因为Nginx只处理HTTP或是HTTPS的流量。

## 2.6 容器网络排查

但是我也踩雷的地方是，我Vaultwarden使用一个内部容器网络连接到Nginx，而只有Nginx可以有互联网的访问权限。所以，当其他配置都设置好之后，依然是无法发送邮件，但是报错的原因是无法解析Gmail的SMTP服务器地址。而容器默认使用主机服务器的DNS服务器，通常都是云服务商的内网DNS服务器。所以问题不在DNS服务器上，作为一个临时的解决方案，我把Vaultwarden的容器又加入到一个有互联网访问权限的容器网络中，然后问题迎刃而解。

## 2.7 邮箱验证

设置后之后回到Vault，会弹出下面的信息。

![250812_vaultwarden_mail_setup8.jpg](/static/img/d72302b1076553d4feb9d647a46e6a09.250812_vaultwarden_mail_setup8.webp)

点击send email，就会有又封邮件发送你的邮箱。正常点击邮件里的链接，就会告诉你邮箱已经验证了。当然了，也可以在设置中把验证邮箱有效性的选项勾掉。

# 3. 创建组织与共享密码条目

## 3.1 新建组织

你的Vault里，选择新建组织 New Organization。这里已经有一个组织了，是和家人共享的一些信息。

![250812_vaultwarden_mail_setup11.jpg](/static/img/d72f187ee3b55b92e363bc9756fdb938.250812_vaultwarden_mail_setup11.webp)

填入组织的名字，默认管理员就是你自己。当然了，可以填写其他人的邮箱，但是没试过会怎么样。

![250812_vaultwarden_mail_setup12.jpg](/static/img/eef71f12fef8337f8d67777a3880b243.250812_vaultwarden_mail_setup12.webp)

## 3.2 新建共享文件夹

创建完组织之后，左边侧边栏会多一个Admin Console的选项。

![250812_vaultwarden_mail_setup13.jpg](/static/img/99be6b46732ce2079eb34c90296b13f2.250812_vaultwarden_mail_setup13.webp)

在Collections里新家一个文件夹，点击右侧的三个点，可以编辑权限。

## 3.3 邀请用户

点击左边侧边栏的用户，再点击右上角的邀请。

![250812_vaultwarden_mail_setup15.jpg](/static/img/5b5a1718992085ded2caa0629fea8bcf.250812_vaultwarden_mail_setup15.webp)

输入邮箱，设置给邀请用户的角色。

![250812_vaultwarden_mail_setup16.jpg](/static/img/1a780683b37765531331ef2b2a4a3eb1.250812_vaultwarden_mail_setup16.webp)

选择分享给邀请用户的文件夹，设置条目的权限。

![250812_vaultwarden_mail_setup17.jpg](/static/img/83baf478a9cf9e2701bfecee2c98da1f.250812_vaultwarden_mail_setup17.webp)

在受邀的用户收到邀请邮件后，可以直接点击邮箱里的链接加入到组织里。再受邀用户没点击邮件里的链接的时候，用户名上面会有提示他还没接受邀请。

设置完毕后，即可愉快地使用共享密码功能！

Vaultwarden 私有密码管理全攻略：管理后台、邮箱配置与共享组织实用指南

![wordpress1.jpg](/static/img/e67bbab7cd6787593c2b84c0542d06ae.wordpress1.webp)
> 这篇文章详细介绍了如何使用 Docker 快速部署 WordPress，包括基础部署、通过 Nginx 实现 HTTPS 反向代理、内网无域名环境下的端口映射修复，以及常见问题的解决方案。文章涵盖从开发环境到生产部署的全流程，并提供实用的配置文件、代码片段和优化技巧，非常适合希望私有部署 WordPress 的开发者或企业团队。



# 1. WordPress 简介：开源建站系统首选
**WordPress** 是一个开源的内容管理系统（CMS），用于创建和管理网站、博客或应用程序。它最初是一个博客平台，但现在已经发展成功能强大、灵活的建站系统。

它支持私有部署，2分钟安装程序，操作界面友好，非技术用户也能轻松上手。它拥有全球最大的社区，大量的主题和插件。技术栈由PHP，MySQL/MariaDB，Apache/Nginx组成。

# 2. 快速部署 WordPress：Docker 初体验
通过Docker来部署Wordpress是最容易的。需要说明的是，默认的Wordpress镜像集成的是Apache，如果要使用Nginx作为Web服务器，则需要选择Wordpress FSM的版本。数据库可以使用MySQL或是MariaDB。

下面是最简单的部署方式，没有代理，没有启用HTTPS，没有Certbot自动更新证书，没有Redis。只需要将Wordpress的80端口映射到服务器上的8080端口后，可以通过 `http://domain_name:8080` 来访问了。 

```yaml
services:
  wordpress:
    image: wordpress:latest
    ports:
      - 8000:80
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_NAME: wp
      WORDPRESS_DB_USER: wpuser
      WORDPRESS_DB_PASSWORD: wppass
    volumes:
      - ./wp-data:/var/www/html

  db:
    image: mysql:5.7
    environment:
      MYSQL_ROOT_PASSWORD: rootpass
      MYSQL_DATABASE: wp
      MYSQL_USER: wpuser
      MYSQL_PASSWORD: wppass
    volumes:
      - ./db-data:/var/lib/mysql
```

访问`http://domain_name:8080` 首先会让你设置你的网站，之后Wordpress会在数据库内新建一个数据库，并把相关的表建立起来。再之后就可以直接访问Wordpress的网站了。默认通过 `http://domain_name:8080/wp-admin`来访问Wordpress的后台。

# 3. 云服务器部署 WordPress：HTTPS + Nginx 实践

我在云服务器上是使用Nginx来代理我所有的应用。对于Wordpress也不例外，我只使用Nginx将请求代理给Wordpress，并没有将Nginx作为Wordpress的Web服务器，所以我还是使用默认的Docker镜像。

## 3.1 WordPress 与数据库容器配置
这里我使用了MariaDB，由Nginx来管理相关的证书并作HTTPS流量的卸载。下面是Wordpress的Docker Compose文件。

我提前规划好了Docker网络，wordpress-net只用于Wordpress和MariaDB的通信，nginx-reverse-proxy网络用于Wordpress和Nginx的通信。

```yaml
services:   
  wordpress:
    image: wordpress:latest
    container_name: wp_web
    depends_on:
      - db
    volumes:
      - ./uploads.ini:/usr/local/etc/php/conf.d/uploads.ini
      - ./html:/var/www/html
    expose:
      - 80
    networks:
      - nginx-reverse-proxy
      - wordpress-net
    restart: always
    environment:
      - WORDPRESS_DB_HOST=wp_db
      - WORDPRESS_DB_USER=wpuser
      - WORDPRESS_DB_PASSWORD=wppassword
      - WORDPRESS_DB_NAME=wpdb

  db:
    image: mariadb:latest
    command: '--default-authentication-plugin=mysql_native_password'
    container_name: wp_db
    volumes:
      - ./mysql:/var/lib/mysql
    restart: always
    environment:
      - MYSQL_ROOT_PASSWORD=root_password
      - MYSQL_DATABASE=wpdb
      - MYSQL_USER=wpuser
      - MYSQL_PASSWORD=wppassword
    expose:
      - 3306
    networks:
      - wordpress-net

networks:
  nginx-reverse-proxy:
    external: true
  wordpress-net:
    external: true
```

## 3.2 Nginx 配置：反向代理与 HTTPS 支持
Nginx的配置文件如下。无论是什么域名的HTTP流量都会重定向到HTTPS。在HTTPS的Server Block里添加你的挂载在Nginx里的证书的位置。

```bash
server {
    listen 80;
    server_name _;

    # Redirect all HTTP requests to HTTPS
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name DOMAIN_NAME;

    # Add this line to increase the limit
    client_max_body_size 100M;

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;

    # SSL/TLS Security Settings
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # Enable HSTS
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    location / {
        proxy_pass http://wp_web:80;
        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;
    }
}
```

## 3.3 附加设置：上传限制与性能优化
此外，Wordpress默认最大上传附件的大小是2M，通过挂载uploads.ini可以改变上传附件大小的限制。此外，在Nginx里，还得设置client_max_body_size，不然Nginx也不放行。下面是uploads.ini的配置，我设置的比较保守。

```bash
file_uploads = On
upload_max_filesize = 16M
post_max_size = 32M
```

这样就是一个生产环境的部署了，我没有使用Certbot来自动更新证书是因为我使用的泛域名的证书，需要用到DNS的challenge。

# 4. 内网环境部署 WordPress：无域名自适应配置

![wordpress_1.jpg](/static/img/0b50809420f197b4f34aa460c8f4807d.wordpress_1.webp)

## 4.1 内网部署挑战与问题排查
由于部署在内网环境之中，没有域名可以使用。所有的应用都在Nginx代理的后面，通过服务器的IP和特殊的端口号来区分应用。正常部署之后发现，重定向之后将端口号给剥离了。经过多次尝试之后，发现要更改多处的配置。正确的配置如下。

## 4.2 容器配置调整：适配内网端口
Wordpress这部分和 3.1部分的配置基本一样，只是添加了一个参数。

```yaml
  wordpress:
    environment:
      WORDPRESS_URL: https://SERVER_IP:CUSTOM_PORT
```

## 4.3 Nginx 配置增强：支持自定义端口
Nginx这部分的配置，除了3.2部分的以外，在location处添加下面的关于CUSTOM_PORT的配置。

```bash
server {
    listen CUSTOM_PORT ssl;
    server_name SERVER_IP;

    省略
    location / {
        proxy_set_header X-Forwarded-Port $server_port;
        proxy_set_header X-Forwarded-Host $host:$server_port;
        proxy_redirect off;
    }
}
```

## 4.4 修改 wp-config.php：URL 与端口兼容性修复

在wordpress_data文件夹下的wp-config.php里添加
```php
/* these 2 clauses are to fix the behavior with custom port behind nginx proxy. */
if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && $_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https') {
    $_SERVER['HTTPS'] = 'on';
}

if (isset($_SERVER['HTTP_X_FORWARDED_HOST'])) {
    $_SERVER['HTTP_HOST'] = $_SERVER['HTTP_X_FORWARDED_HOST'];
}

/* Manually add WP URL and Home URL */
define('WP_HOME', 'https://SERVER_IP:CUSTOM_PORT');
define('WP_SITEURL', 'https://SERVER_IP:CUSTOM_PORT');

```

然后docker compose restart重启整个Wordpress容器。
# 5. 实用技巧与界面客制化建议

强制登录，和登录界面客制化都可以通过插件来实现。但是我想把后台的Wordpress图标和相关的超链接给去掉。在wordpress_data文件夹下的wp-content/themes/hybridmag/functions.php里添加下面的代码来移除所有的后台左上角的Wordpress Logo和相应的链接。你用的哪个主题就在哪个主题下更改。

```php
function remove_wp_logo_from_admin_bar($wp_admin_bar) {
    $wp_admin_bar->remove_node('wp-logo');         // Main logo
    $wp_admin_bar->remove_node('about');           // About WordPress
    $wp_admin_bar->remove_node('wporg');           // WordPress.org
    $wp_admin_bar->remove_node('documentation');   // Documentation
    $wp_admin_bar->remove_node('support-forums');  // Support
    $wp_admin_bar->remove_node('feedback');        // Feedback
}
add_action('admin_bar_menu', 'remove_wp_logo_from_admin_bar', 11);
```

WordPress私有部署全指南：从入门到生产环境优化

![openldapcli.jpg](/static/img/e490142cdffff1a80f1370b4c5d17d8a.openldapcli.webp)
> 本文详细介绍了 OpenLDAP 的命令行操作，涵盖了从基础的用户和组管理（包括用户创建、组分配及成员关系检查）到高级的服务器配置（如 `slapd` 守护进程的工作原理及其配置方式）。通过具体的 LDIF 文件示例和 `ldapadd`、`ldapmodify`、`ldapsearch` 等常用工具的演示，帮助读者全面理解和掌握 OpenLDAP 的数据管理与服务器维护。特别强调了从传统 `slapd.conf` 到动态 `cn=config` 配置的演进，并提供了 `cn=config` 的实际修改案例。



# 1. OpenLDAP 命令行数据管理实践

OpenLDAP可以使用WEBUI来管理，也可以使用命令行来管理。OpenLDAP的部署请参考 [OpenLDAP 部署与基本原理解析（含 Docker Compose 与 Nginx 代理配置）](https://www.zenseek.site/post/8)。

我们今天使用命令行来进行LDAP的操作，一步一步演示怎么添加用户和组并将用户添加到组中。
## 1.1 基本连接测试

先测试账号密码是否能登录Openldap，再尝试显示DN下所有的对象。

```bash

ldapwhoami -x -H ldap://localhost:389 -D "cn=admin,dc=example,dc=com" -W
Enter LDAP Password: 
dn:cn=admin,dc=example,dc=com

ldapsearch -x -H ldap://localhost:389 -D "cn=admin,dc=example,dc=com" -W -b "dc=example,dc=com" "(objectClass=*)"
Enter LDAP Password: 
# extended LDIF
#
# LDAPv3
# base <dc=example,dc=com> with scope subtree
# filter: (objectClass=*)
# requesting: ALL
#

# example.com
dn: dc=example,dc=com
objectClass: top
objectClass: dcObject
objectClass: organization
o: MyOrg
dc: example

# search result
search: 2
result: 0 Success

# numResponses: 2
# numEntries: 1
```

## 1.2 用户账户创建
新建一个OU的LDIF文件。
```bash
# add_ou_people.ldif
dn: ou=People,dc=example,dc=com
objectClass: organizationalUnit
ou: People
description: All people in the organization
```

添加新的OU。
```bash
ldapadd -x -H ldap://localhost:389 -D "cn=admin,dc=example,dc=com" -W -f add_ou_people.ldif

Enter LDAP Password: 
adding new entry "ou=People,dc=example,dc=com"
```

在Openldap内部生成密码哈希。
```bash
root@69a9b6c75c35:/# slappasswd -s "userpass"
{SSHA}lP2pSP56cT5EE98/bkvcNY8zJ0bB6O6n
```

新建一个User的LDIF文件。
```bash
# add_test_user.ldif
dn: cn=testu,ou=People,dc=example,dc=com
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: testu
sn: User
givenName: Test
mail: test.user@example.com
uid: 1000
userPassword: {SSHA}lP2pSP56cT5EE98/bkvcNY8zJ0bB6O6n
description: General test user account
```

添加新的User。
```bash
ldapadd -x -H ldap://localhost:389 -D "cn=admin,dc=example,dc=com" -W -f add_test_user.ldif

Enter LDAP Password: 
adding new entry "cn=testu,ou=People,dc=example,dc=com"
```

## 1.3 用户组创建与管理

新建一个OU为Groups的LDIF文件。
```bash
# add_ou_groups.ldif
dn: ou=Groups,dc=example,dc=com
objectClass: organizationalUnit
ou: Groups
description: All groups in the organization
```

添加新的OU Groups。
```bash
ldapadd -x -H ldap://localhost:389 -D "cn=admin,dc=example,dc=com" -W -f add_ou_groups.ldif

Enter LDAP Password: 
adding new entry "ou=Groups,dc=example,dc=com"
```

新建一个Group的LDIF文件。
```bash
# add_new_group_testg.ldif
dn: cn=testg,ou=Groups,dc=example,dc=com
objectClass: top
objectClass: groupOfUniqueNames
cn: testg
description: My new test group
uniqueMember: cn=testu,ou=People,dc=example,dc=com
```

添加新的Group并分配User。
```bash
ldapadd -x -H ldap://localhost:389 -D "cn=admin,dc=example,dc=com" -W -f add_new_group_testg.ldif
Enter LDAP Password: 
adding new entry "cn=testg,ou=Groups,dc=example,dc=com"
```

检查Test User是否属于Test Group。
```bash
ldapsearch -x -H ldap://localhost:389 -D "cn=admin,dc=example,dc=com" -W   -b "cn=testg,ou=Groups,dc=example,dc=com"   "(uniqueMember=cn=testu,ou=People,dc=example,dc=com)"   dn
Enter LDAP Password: 
# extended LDIF
#
# LDAPv3
# base <cn=testg,ou=Groups,dc=example,dc=com> with scope subtree
# filter: (uniqueMember=cn=testu,ou=People,dc=example,dc=com)
# requesting: dn 
#

# testg, Groups, example.com
dn: cn=testg,ou=Groups,dc=example,dc=com

# search result
search: 2
result: 0 Success

# numResponses: 
```

## 1.4 用户信息更新

新建一个修改用户的LDIF文件。
```bash
# modify_user.ldif
dn: cn=testu,ou=People,dc=example,dc=com
changetype: modify
replace: sn
sn: NewSurname
-
replace: givenName
givenName: NewGivenName
-
add: mobile
mobile: 18812345678
-
delete: mail
```

更改姓和名，新增手机号码，删除邮件地址。每一项操作中间添加分隔符 `-` 。
```bash
ldapmodify -x -H ldap://localhost:389 -D "cn=admin,dc=example,dc=com" -W -f modify_user.ldif
Enter LDAP Password: 
modifying entry "cn=testu,ou=People,dc=example,dc=com"
```
# 2. OpenLDAP 命令行工具速查

命令行分为客户端和服务端两大类。
## 2.1 客户端工具 (用于管理 LDAP 数据)
下面示例，客户端和服务端在同一个服务器上，所以使用localhost。如果是不在同一个服务器上，则需要指定-H后面的域名或是IP，为了安全考虑，要使用加密连接 如ldaps://IP:636。

1. **`ldapsearch`**
- 用途： 从 LDAP 目录中查询和检索信息。它是最常用的工具，用于验证条目、查找用户、组等。 
- 示例： `ldapsearch -x -H ldap://localhost:389 -b "dc=example,dc=com" "(objectClass=inetOrgPerson)"`
2. **`ldapadd`**
- 用途: 向 LDAP 目录添加新的条目（例如用户、组、组织单位）。它通常与 LDIF (LDAP Data Interchange Format) 文件一起使用。 
- 示例： `ldapadd -x -H ldap://localhost:389 -D "cn=admin,dc=example,dc=com" -W -f new_user.ldif`
3. **`ldapmodify`**
- 用途： 修改 LDAP 目录中现有条目的属性。它也通常与 LDIF 文件一起使用，文件指定了要进行的修改类型（添加、替换、删除属性值）。 
- 示例： `ldapmodify -x -H ldap://localhost:389 -D "cn=admin,dc=example,dc=com" -W -f modify_user.ldif`
4. **`ldapdelete`**
- 用途： 从 LDAP 目录中删除条目。 
- 示例： `ldapdelete -x -H ldap://localhost:389 -D "cn=admin,dc=example,dc=com" -W "cn=testu,ou=People,dc=example,dc=com"`
5. **`ldappasswd`**
- 用途： 更改 LDAP 目录中用户的密码。 
- 示例：
    - 用户 `testu` 更改自己的密码：`ldappasswd -x -H ldap://localhost:389 -D "cn=testu,ou=People,dc=example,dc=com" -W -s "new_password"`
    - 管理员更改 `testu` 用户的密码：`ldappasswd -x -H ldap://localhost:389 -D "cn=admin,dc=example,dc=com" -W -s "new_password_for_testu" "cn=testu,ou=People,dc=example,dc=com"`
6. **`ldapwhoami`**
- 用途： 验证当前用户是否成功通过 LDAP 服务器认证，并显示认证后的 DN。常用于测试认证连接。 
- 示例： `ldapwhoami -x -H ldap://localhost:389 -D "cn=testu,ou=People,dc=example,dc=com" -W`

## 2.2 服务器端工具 (用于管理 OpenLDAP 服务器)

这些工具通常在 OpenLDAP 服务器主机上运行，并且通常需要 root 权限或 OpenLDAP 用户的权限。譬如在容器内部显示可以用的slap命令。最常用的是数据库的导入导出。
```bash
root@69a9b6c75c35:/# slap
slapacl     slapadd     slapauth    slapcat     slapd       slapdn      slapindex   slappasswd  slapschema  slaptest 
```

1. **`slapcat`**
- 用途： 将整个 OpenLDAP 数据库或其一部分导出为 LDIF 格式。常用于备份或迁移数据。 
- 示例： `slapcat -b "dc=example,dc=com" -l backup.ldif`
2. **`slapadd`**
- 用途： 将 LDIF 文件中的数据批量导入到 OpenLDAP 数据库中。通常用于恢复备份或初始化数据库。 
- 示例： `slapadd -b "dc=example,dc=com" -l backup.ldif`
3. **`slapindex`**
- 用途： 重建 OpenLDAP 数据库的索引。在更改索引配置或数据损坏时可能需要。 
- 示例： `slapindex -b "dc=example,dc=com"`
4. **`slaptest`**
- 用途： 检查 OpenLDAP 配置文件 (`slapd.conf` 或 `cn=config` 目录) 的语法是否正确。在启动 `slapd` 服务之前进行配置验证非常有用。 
- 示例： `slaptest -f /etc/ldap/slapd.conf -u`

# 3. OpenLDAP 核心守护进程 Slapd 及其配置

`slapd` 是 OpenLDAP 项目的核心组件，它是 **OpenLDAP Directory Server** 的守护进程（daemon）。简单来说，`slapd` 就是 OpenLDAP 服务器本身，它负责处理所有对 LDAP 目录的请求，包括认证、查询、添加、修改和删除条目等。

## 3.1 Slapd的作用

- **监听 LDAP 请求：** `slapd` 监听标准的 LDAP 端口（默认 389 用于非加密连接，636 用于 LDAPS/SSL/TLS 加密连接），等待客户端（如 `ldapsearch`, `ldapadd`, `ldapmodify` 等）的连接。
- **处理请求：** 接收到请求后，`slapd` 会根据其配置、目录数据和访问控制列表（ACLs）来处理这些请求。
- **管理数据存储：** `slapd` 管理后端数据库，负责数据的持久化存储和检索。MDB (Memory-Mapped Database / LMDB) 是由 Symas Corporation 开发，并作为 OpenLDAP 项目的一部分发布的。它现在是 OpenLDAP **默认和推荐**的数据库后端。
- **执行认证和授权：** 根据用户提供的凭据进行认证，并根据配置的 ACLs 决定用户是否有权限执行特定操作。

## 3.2 传统配置方式：slapd.conf (已弃用)

基于文本文件的配置模式。在容器中的位置为`/etc/ldap/ldap.conf`。和Nginx的配置文件类似，每次更改配置后需要检查配置有效性并重启服务。文件示例：

```bash
root@69a9b6c75c35:/etc/ldap# cat ldap.conf 
#
# LDAP Defaults
#

# See ldap.conf(5) for details
# This file should be world readable but not world writable.

#BASE   dc=example,dc=com
#URI    ldap://ldap.example.com ldap://ldap-master.example.com:666

#SIZELIMIT      12
#TIMELIMIT      15
#DEREF          never

# TLS certificates (needed for GnuTLS)
TLS_CACERT /container/run/service/slapd/assets/certs/ca.crt

TLS_REQCERT never
```

关于TLS的配置是Docker Compose里面的环境变量的映射。这种方式已不再使用，进而转变到基于 LDAP 目录本身的动态配置。

## 3.3 动态运行时配置：cn=config (推荐)

`cn=config` 是一种将 `slapd` 的配置本身存储为 LDAP 目录中的特殊条目的方式。这意味着你可以像管理普通 LDAP 数据一样，使用标准的 LDAP 工具（如 `ldapadd`, `ldapmodify`, `ldapdelete`）来实时修改 `slapd` 的配置，而无需重启服务。

`cn=config` 并不是一个单一的文件。它通常对应文件系统上的一个目录（例如 `/etc/ldap/slapd.d/`），该目录下包含一系列的 LDIF 文件，每个文件代表一个配置条目。这些 LDIF 文件在 `slapd` 启动时被读取并加载到内存中，之后对配置的修改会直接反映在内存中，并同步更新到这些 LDIF 文件。

```bash
root@69a9b6c75c35:/etc/ldap# ls slapd.d/
'cn=config'  'cn=config.ldif'   docker-openldap-was-admin-password-set   docker-openldap-was-started-with-tls
root@69a9b6c75c35:/etc/ldap/slapd.d# ls cn\=config
'cn=module{0}.ldif'  'cn=schema.ldif'              'olcDatabase={-1}frontend.ldif'  'olcDatabase={1}mdb.ldif'
'cn=schema'          'olcDatabase={0}config.ldif'  'olcDatabase={1}mdb'
```

通过下面的命令可以查看所有的配置，它非常的冗长。
```bash
root@69a9b6c75c35:/etc/ldap/slapd.d# ldapsearch -Y EXTERNAL -H ldapi:/// -b "cn=config"
......省略

# {0}memberof, {1}mdb, config
dn: olcOverlay={0}memberof,olcDatabase={1}mdb,cn=config
objectClass: olcOverlayConfig
objectClass: olcMemberOf
olcOverlay: {0}memberof
olcMemberOfDangling: ignore
olcMemberOfRefInt: TRUE
olcMemberOfGroupOC: groupOfUniqueNames
olcMemberOfMemberAD: uniqueMember
olcMemberOfMemberOfAD: memberOf

# {1}refint, {1}mdb, config
dn: olcOverlay={1}refint,olcDatabase={1}mdb,cn=config
objectClass: olcOverlayConfig
objectClass: olcRefintConfig
olcOverlay: {1}refint
olcRefintAttribute: owner
olcRefintAttribute: manager
olcRefintAttribute: uniqueMember
olcRefintAttribute: member
olcRefintAttribute: memberOf

......省略
```

更改配置就和更改其他目录里的条目是类似的。创建一个LDIF文件并应用它。譬如修改上面例子里的配置，`olcRefintAttribute` 是一个多值属性。

```bash
# delete_refint_attr.ldif
dn: olcOverlay={1}refint,olcDatabase={1}mdb,cn=config
changetype: modify
delete: olcRefintAttribute
olcRefintAttribute: owner
```

修改 `cn=config` 配置通常需要使用 `EXTERNAL` SASL 机制通过 Unix Domain Socket (`ldapi:///`) 进行认证。这意味着你需要以 `root` 用户或 `slapd` 进程所属的用户身份执行 `ldapmodify` 命令。在容器内部，就是以root用户运行的。
```bash
root@69a9b6c75c35:/etc/ldap/slapd.d# ldapmodify -Y EXTERNAL -H ldapi:/// -f delete_refint_attr.ldif
```