>w **警告提示**
>
> 如果使用 Windows 自带的记事本编辑配置文件，一定要保存为「UTF-8 无 BOM」的格式。

MrDoc 无需配置、开箱即用。

同时，MrDoc 还支持使用配置文件自定义站点的一些配置项。

配置文件位于项目（MrDoc/MrDocPro）的`config`文件夹内，名为`config.ini`。
**==如果文件夹内无此文件，可以自行创建。==**

> d 提示：如果应用已经运行，修改配置文件后，必须重启应用（Docker 部署方式重启 Docker 容器）。  
> 提示：如果应用已经运行，修改配置文件后，必须重启应用（Docker 部署方式重启 Docker 容器）。  
> 提示：如果应用已经运行，修改配置文件后，必须重启应用（Docker 部署方式重启 Docker 容器）。

## 开启站点调试

默认情况下，站点为「非调试」模式，如果你需要开启站点调试模式，那么可以在配置文件中写入如下内容：

```
[site]
# True表示开启站点调试模式，False表示关闭站点调试模式
debug = True
```

修改配置文件后，请重启应用/Docker容器。

## 数据库配置

默认情况下，MrDoc 使用 SQLite 数据库。如果你有使用其他数据库的需求，可以在配置文件中指定数据库相关配置信息。

>d 配置数据库必须在执行`python manage.py makemigrations` 命令之前。否则，原有数据会丢失！

>d 部署后更换数据库，务必进行数据导出备份，否则原有数据会丢失！

### 安装数据库依赖

>i **信息提示**
>
> 官方 Docker 镜像已包含 MySQL、PostgreSQL数据库依赖，Docker 部署方式无需额外安装

- PostgreSQL 数据库请安装`psycopg`，PostgreSQL >= 12
- MySQL 数据库请安装`mysqlclient`，MySQL >= 8.0
- Oracle 数据库请安装`cx_Oracle`，Oracle >= 19c

除 SQLite 外，MrDoc 还支持如下数据库：

- MySQL
- Oracle
- PostgreSQL

具体配置项如下所示：

```
[database]
# engine，指定数据库类型，接受sqlite、mysql、oracle、postgresql
engine = mysql
# name表示数据库的名称
name = db_name
# user表示数据库用户名
user = db_user
# password表示数据库用户密码
password = db_pwd
# host表示数据库主机地址
host = db_host
# port表示数据库端口
port = db_port
```

修改配置文件后，请重启应用/Docker容器。

## 站点语言和时区配置

>i 在不配置`force = True`的情况下，不同语言环境的浏览器显示出来的可能会是其他的语言，这是因为觅思文档使用的 Django 框架有一套发现和使用语言翻译包的机制，详见：https://docs.djangoproject.com/zh-hans/4.2/topics/i18n/translation/#how-django-discovers-language-preference  。
>
>如果你需要强制觅思文档在所有浏览器语言环境中都使用一种语言，那么可以指定`force = True`

默认情况下，站点语言显示为「中文简体」，时区为`Asia/Shanghai`。

目前，MrDoc 支持如下语言：

- 中文简体(zh-hans)
- 中文繁體(zh-hant)
- English(en)

如果需要有其他语言和时区，可以进行如下配置：

```
[locale]
# 语言
language = zh-hant
# 时区
timezone = America/Chicago
# 强制使用设置的语言，默认为False
force = True
```

修改配置文件后，请重启应用/Docker容器。

## Session 会话配置

```
[session]
# 会话过期时间，单位为秒，默认为1周
cookie_age = 604800
# 浏览器关闭即过期，默认为False
browser_close = True
# 安全Cookie，默认为False
cookie_secure = False
# HttpOnly，默认为True
cookie_httponly = True
```

修改配置文件后，请重启应用/Docker容器。

## PDF下载配置

> i MrDoc 官方 docker 运行环境镜像无需配置

MrDoc 内置了一个文集导出 PDF 的功能，这个功能依赖于 Chromium 和 chromedriver 程序。如果需要实现 PDF 导出功能，请先在计算机上安装 Chromium 或 Chrome，然后在配置文件中进行配置：

```
[selenium]
# 在Windows环境下测试或使用，请配置driver = Chrome，否则不用配置 driver 参数
driver = Chrome
# 如果系统无法正确安装或识别chromedriver，请指定chromedriver在计算机上的绝对路径
driver_path = driver_path
```

修改配置文件后，请重启应用/Docker容器。

## 图片上传格式

默认情况下，MrDoc 允许`jpg,jpeg,gif,png,bmp,webp`这些格式的图片进行上传。如果你需要自定义允许上传图片的格式，可以在配置文件中写入（格式之间以英文逗号,分隔）：

```
[image_upload]
# 允许上传的图片格式
suffix_name = jpg,jpeg,gif,png,bmp,webp
```

>d 警告：SVG等支持嵌入代码的格式图片会带来极大的安全风险，请谨慎允许此类格式的图片上传。

修改配置文件后，请重启应用/Docker容器。

## 扩展媒体目录

默认情况下，MrDoc 从`media`目录中寻找用户上传的媒体文件（图片、附件等），如果你的文档里的图片或文件使用的是别的目录，可以将目录复制到 MrDoc 的根目录之后，在配置文件中指定一个新的媒体目录：

```
[extend_media]
# 状态，默认为False
is_enable = True
# 目录路径
root_path = images
```

> 此功能只能作为临时之用途，站点中新上传的图片和附件还是会上传到 media 目录中。

修改配置文件后，请重启应用/Docker容器。

## CSRF 可信来源配置

```
[csrf_origin]
allow = 主机名
```

如果存在多个主机用英文逗号分隔，例如：
```
[csrf_origin]
allow = https://doc.mrdoc.pro,http://mrdoc.mrdoc.com,https://112.154.12.12
```

修改配置文件后，请重启应用/Docker容器。

## 跨域域名配置

```
[cors_origin]
allow = URL
```

例如：

```
[cors_origin]
allow = http://baidu.com,http://192.168.1.1:8008
```

修改配置文件后，请重启应用/Docker容器。

## 开启 IFrame 嵌入支持

默认情况下，MrDoc 不支持被嵌入到跨域的`iframe`标签中。如果你需要将 MrDoc 嵌入到跨域的`iframe`标签中，可以进行如下配置：

```
[x_frame]
option = ALLOWALL
```

修改配置文件后，请重启应用/Docker容器。

## 配置文本文件访问

在域名验证等场景下，可能需要在根路径下配置一个文本文件以供访问和验证。一般情况下，这种配置交给 Nginx 处理会更好，但是如果你需要在觅思文档中配置，请进行如下操作。

第一步，将文本文件放置到应用的`template`目录下。

开源版：`/MrDoc/template`  
专业版：`/MrDocPro/template`

如果你基于官方Docker部署  ，且未修改任何路径，那么其目录为：

开源版：`/opt/MrDoc/template`  
专业版：`/opt/MrDocPro/template`

第二步，在配置文件中进行如下配置。

```
[extend_root_txt]
filename = 文本文件名
```

例如：

```
[extend_root_txt]
filename = ads.txt
```

多个文件用英文逗号`,`分隔

完成配置之后，你可以通过`根路径+文本文件名`访问到配置到的文本文件，例如：`https://doc.mrdoc.pro/ads.txt`

修改配置文件后，请重启应用/Docker容器。

## 第三方缓存配置

MrDoc觅思文档默认使用内存缓存，如果你有配置其他缓存数据库的需求，可以进行如下配置：

```
[cache]
backend = {缓存类型}
location = {缓存链接}
```

backend支持如下参数：

- `memcached`：Memcached数据库缓存
- `redis`：Redis数据库缓存
- `filebase`：文件系统缓存
- `locmem`：本地内存缓存

location 即是所配置缓存类型的链接地址。

### Memcached配置示例

```
[cache]
backend = memcached
location = 127.0.0.1:11211
```

### Redis配置示例

```
[cache]
backend = redis
location = redis://myuser:mypassword@127.0.0.1:6379
```

### 文件系统缓存配置示例

```
[cache]
backend = filebase
location = /var/tmp/mrdoc_cache
```

## 关闭 Sitemap 站点地图

默认情况下，MrDoc 开启网站的站点地图功能，如果你不需要此功能，可以在配置文件中进行关闭：

```
[sitemap]
status = False
```

修改配置文件后，请重启应用/Docker容器。

## 附件预览（专业版）

> i MrDoc 官方 docker 运行环境镜像无需配置

```
[preview]
# LibreOffice 程序路径，需自行在服务器上安装
libreoffice_path = C://Program Files//LibreOffice//program//soffice.exe
```

LibreOffice 安装方法见：[《LibreOffice 安装说明》](https://doc.mrdoc.pro/doc/44895/)

修改配置文件后，请重启应用/Docker容器。

## 附件格式白名单校验（专业版）

```
[attachment_suffix]
# 是否开启验证，True 表示开启，False表示关闭，默认为True
# 关闭后上传的附件将不再验证指定的白名单格式
is_enable = False
```

修改配置文件后，请重启应用/Docker容器。

## 仓库账号配置（专业版）

在 MrDoc 专业版中，需要配置专业版私有仓库的账号以实现版本的更新检测功能。

```
[liscense]
git_user = 用户名
git_pwd = 用户密码
```

修改配置文件后，请重启应用/Docker容器。

配置文件说明