开发文档Umo Office Convert环境变量

环境变量配置

.env 文件主要用于配置应用程序的运行环境和各项参数,实现配置与代码分离,便于不同环境(开发/测试/生产)的部署管理。通过修改配置文件即可调整应用行为,无需修改源代码,提高部署灵活性和安全性。

您需要复制根目录下的 .env.example 并重命名为 .env 放置于根目录下,并根据实际需要修改对应配置。

配置项说明

完整的 .env 文件配置示例见 .env.example,以下是配置项的详细说明。

Node 环境配置

# node 环境
NODE_ENV = production

服务相关配置

# 服务端口
PORT = 1236
# 服务名称
SERVER_NAME = Umo Office Convert

日志配置

# 日志存放路径
LOG_DIR = ./logs

文件上传配置

# 最大允许上传的文件大小,单位为 MB
MAX_FILE_SIZE = 50

文档存储路径配置

# 上传的文档存放路径
UPLOAD_DIR = ./uploads/[year]/[month]
# 转换后的文档存放路径
CONVERTED_DIR = ./converted/[year]/[month]

文件哈希算法配置

FILE_HASH_ALGORITHM = sha256

MySQL 数据库配置

DB_HOST = localhost
DB_PORT = 3306
DB_USER = root
DB_PASSWORD =
DB_NAME = umo_office_convert

Webhook 配置

# Webhook 地址,用于接收文件上传和转换完成的通知
CONVERTED_WEBHOOK_URL =

访问控制配置

# 允许访问服务的 IP 地址列表,多个 IP 地址之间用逗号分隔,设置为 `*` 或留空表示允许所有来源
WHITE_LIST = 127.0.0.1, 0.0.0.0, localhost

重要说明

路径变量说明

  • [year][month][day] 为动态路径变量,系统会根据当前日期自动替换。例如:./uploads/[year]/[month] 可能会生成 ./uploads/2024/01 这样的路径
  • 如果未指定上传路径,则不保存上传的文件

安全注意事项

  1. 数据库密码DB_PASSWORD 需要根据实际环境设置
  2. 白名单配置WHITE_LIST 用于限制访问 IP,生产环境建议配置具体的 IP 地址
  3. 文件大小限制MAX_FILE_SIZE 可根据实际需求调整,避免服务器资源耗尽

哈希算法选择

  • 文件哈希算法,用于生成文件的唯一标识符, 支持的算法列表会根据你使用的 Node.js 版本、操作系统和 OpenSSL 版本而异,常见的有 md5, sha1, sha256, sha512
  • 如果更改哈希算法,需要确保数据表中的 hash 字段长度足够存储哈希值

Webhook 功能

  • CONVERTED_WEBHOOK_URL 用于接收文件处理状态通知,其配置的地址需要支持接收 POST 请求,且无需授权
  • 当文件上传或文件转换完成后,系统会向配置的 Webhook URL 发送 POST 请求,包含转换任务的相关信息。
  • 留空或不配置则表示不启用 Webhook 功能