MrDoc二级域名配置+优化（直接复制粘贴版）

### 一、核心目标

1. 用二级域名（如 [doc.yourdomain.com](https://doc.yourdomain.com)）访问 MrDoc，无需加端口号；

2. 优化访问速度，解决卡顿、加载慢问题；

3. 兼容宝塔面板，不破坏原有配置逻辑。

### 二、前置条件

* 已部署 Docker 版 MrDoc（默认端口 10086）；

* 二级域名已完成 DNS 解析（A 记录指向服务器 IP）；

* 宝塔面板已安装 Nginx。

### 三、关键配置步骤

#### 1. 二级域名 DNS 解析

* 登录域名服务商后台（阿里云 / 腾讯云等）；

* 新增 A 记录：主机记录填「doc」（二级域名 [doc.yourdomain.com](https://doc.yourdomain.com)），记录值填服务器公网 IP，TTL=300 秒；

* 验证：ping [doc.yourdomain.com](https://doc.yourdomain.com)，能解析到服务器 IP 即生效。

#### 2. 宝塔 Nginx 反向代理配置（核心）

##### 2.1 新建反向代理规则

* 宝塔面板 → 网站 → 新增站点：

* 域名：[doc.yourdomain.com](https://doc.yourdomain.com)；

* 根目录：随便填（反向代理用不到）；

* 进入该站点 → 反向代理 → 添加反向代理：

* 代理名称：mrdoc-proxy；

* 目标 URL：[http://127.0.0.1:10086](http://127.0.0.1:10086)；

* 保存后，通过文件管理器编辑代理规则文件。

##### 2.2 优化反向代理规则（关键提速）

* 规则文件路径：/www/server/panel/vhost/nginx/proxy/[doc.yourdomain.com/\*.conf](https://doc.yourdomain.com/*.conf)；

* 替换为以下优化配置：

```Nginx
#PROXY-START/
location ^~ /
{
    proxy_pass http://127.0.0.1:10086;
    # 修复Host头，让MrDoc识别真实域名
    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 REMOTE-HOST $remote_addr;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_http_version 1.1;

add_header X-Cache $upstream_cache_status;

# 缓冲区优化（核心提速）
    proxy_buffer_size 128k;
    proxy_buffers 4 256k;
    proxy_busy_buffers_size 256k;
    # 延长超时，避免大文档加载中断
    proxy_read_timeout 600s;
    proxy_connect_timeout 60s;

# 静态资源缓存（图片/CSS/JS缓存12小时）
    set $static_filesNBw3DZq 0;
    if ( $uri ~* "\.(gif|png|jpg|css|js|woff|woff2)$" )
    {
        set $static_filesNBw3DZq 1;
        expires 12h; # 缓存12小时，大幅提速
    }
    if ( $static_filesNBw3DZq = 0 )
    {
        add_header Cache-Control no-cache; # 动态内容（文章/笔记）不缓存，实时更新
    }
}
#PROXY-END/
```

#### 3. 修复 Nginx 主配置冲突

* 问题：新增缓冲区配置后，报错「proxy\_temp\_file\_write\_size must be ≥ proxy\_buffers」；

* 解决：

1. 打开 Nginx 主配置：/www/server/nginx/conf/nginx.conf；

2. 找到并打开 proxy.conf（nginx.conf 中包含 `include proxy.conf;`）；

3. 在 proxy.conf 中添加 / 修改：`proxy_temp_file_write_size 256k;`（与 proxy\_buffers 单块大小一致）；

4. 保存后，宝塔面板 → 软件商店 → Nginx → 重启。

### 四、优化效果说明

| 优化项          | 效果                                                                 |
| ------------ | ------------------------------------------------------------------ |
| 二级域名访问       | 直接访问 [doc.yourdomain.com](https://doc.yourdomain.com)，无需加 10086 端口 |
| 长连接 + 缓冲区优化  | 页面跳转、文档加载无卡顿                                                       |
| 静态资源缓存 12 小时 | 图片 / CSS/JS 二次加载秒开                                                 |
| 动态内容不缓存      | 文章、笔记修改后实时显示                                                       |

### 五、常见问题排查

1. **访问域名显示 Nginx 默认页**：

* 解决：删除 Nginx 默认配置 → 宝塔 → 网站 → 删除默认站点，重启 Nginx；

1. **502 错误**：

* 检查 MrDoc 容器是否运行：`docker ps | grep mrdoc`，确保 10086 端口未被占用；

1. **静态资源修改后不显示**：

* 自己测试：Ctrl+F5 强制刷新；

* 给用户看：访问 `http://doc.yourdomain.com/purge/资源路径`（如 /static/images/logo.png）清缓存；

1. **Nginx 重启失败**：

* 查看错误日志：/www/wwwlogs/nginx\_error.log，排查语法错误或重复配置。

### 六、进阶建议（可选）

1. 配置 HTTPS：

* 宝塔 → 网站 → [doc.yourdomain.com](https://doc.yourdomain.com) → SSL → 申请 Let’s Encrypt 免费证书，自动配置；

1. 频繁修改的静态资源（如 LOGO）跳过缓存：

* 在反向代理规则中添加：

```
if ( \$uri \~\* "/static/images/logo.png" ) {

&#x20;   set \$static\_filesNBw3DZq 0; # 强制不缓存

}
```

> （注：文档部分内容可能由 AI 生成）