私有化部署指南

选择部署系统，查看安装与运行步骤。

服务器配置

项目	推荐配置
操作系统	Windows 11 或 Windows Server 2022，64 位 x64
CPU	2 核
内存	4 GB
带宽	5 Mbps
磁盘	40 GB

使用 Windows x64 安装包。

安装依赖

依赖	用途	安装方式
LibreOffice	Word、Excel、PPT 转 PDF	随安装包提供
Java 17 + 转换组件	OFD、TIFF、DICOM 转换	随安装包提供
Poppler	读取 PDF 页数、生成页面图片	随安装包提供
qpdf	单页 PDF、试读裁剪、PDF 合并	随安装包提供
中文字体	中文显示与排版	使用随包字体及系统字体

完整 Windows 安装包已包含以上运行组件，解压后执行安装脚本即可。默认使用 LibreOffice。

使用微软 Office 或 WPS

另行安装相应软件，并选择手动启动方式。Word、PPT 的精准模式和图片模式都需要 Office 转换器。

命令行

powershell -ExecutionPolicy Bypass -File .\install.ps1 -InstallDir "D:\96DOC" -ManualStart

在安装目录的 doc-preview.env 中设置 OFFICE_ENGINE=msoffice 或 OFFICE_ENGINE=wps，再由登录用户执行 start.cmd。此方式不使用 SYSTEM 开机任务。

首次部署

联系我们提供服务器系统和 MAC 地址，获取 Windows 部署包及授权。
解压 ZIP；确认解压目录包含 doc-preview.exe、install.ps1、runtime 和 license.dat。
以管理员身份打开 PowerShell，进入解压目录并执行：

命令行

powershell -ExecutionPolicy Bypass -File .\install.ps1 `
  -InstallDir "D:\96DOC" `
  -PublicURL "http://服务器IP:8088"

将服务器IP替换为实际地址。安装器创建 96DOC Preview 开机启动任务，并启动服务。

安装内容	位置
安装目录	`D:\96DOC`
配置文件	`D:\96DOC\doc-preview.env`
缓存目录	`D:\96DOC\data`
日志目录	`D:\96DOC\logs`

访问 http://服务器IP:8088/demo 验证预览。云安全组与防火墙需允许 TCP 8088。

机器授权

服务授权绑定目标服务器 MAC 地址和截止时间。企业部署包已附带对应的 license.dat；首次安装前放在解压包根目录。

获取本机 MAC 地址：

命令行

Get-NetAdapter | Where-Object { $_.Status -eq "Up" } | Select-Object Name, MacAddress
# 如已取得程序，也可执行 .\doc-preview.exe --mac

将一条已启用网卡的 MAC 地址提供给我们。授权到期、更换服务器或网卡时，请联系我们取得新授权。

续期后，将新文件替换到以下位置，再重启服务：

命令行

D:\96DOC\license.dat

启动与重启

启动服务

命令行

Start-ScheduledTask -TaskName "96DOC Preview"

重启服务

命令行

Stop-ScheduledTask -TaskName "96DOC Preview"
Start-ScheduledTask -TaskName "96DOC Preview"

停止服务

命令行

Stop-ScheduledTask -TaskName "96DOC Preview"

更新程序

联系我们获取更新包，以管理员 PowerShell 在新包解压目录执行：

命令行

powershell -ExecutionPolicy Bypass -File .\install.ps1 -InstallDir "D:\96DOC"

安装器停止已有任务，更新程序和组件，保留已有配置及缓存，再启动服务。

检查服务与日志

命令行

Invoke-RestMethod http://127.0.0.1:8088/health
Get-Content "D:\96DOC\logs\service-error.log" -Tail 100

手动安装模式由登录用户运行安装目录中的 start.cmd；停止控制台进程后再次执行即可重启。

服务配置

配置文件：D:\96DOC\doc-preview.env。每行填写一个 参数=值，修改后重启服务。

命令行

LISTEN_ADDR=0.0.0.0:8088
PUBLIC_BASE_URL=http://服务器IP:8088
DATA_DIR=data
KEY=业务接口密钥
ALLOWED_HOSTS=files.example.com,bucket.oss-cn-hangzhou.aliyuncs.com
ALLOWED_IPS=
TRUSTED_PROXIES=127.0.0.1,::1
CACHE_TTL_HOURS=168
CACHE_MAX_MB=2048
WORKERS=1
OFFICE_ENGINE=libreoffice

参数	默认值 / 示例	用途
`LISTEN_ADDR`	0.0.0.0:8088	Go 服务监听地址。仅本机代理访问可用 127.0.0.1:8088；公网需放行安全组和防火墙的 8088。不会占用 80。
`PUBLIC_BASE_URL`	留空；实际部署应填写	浏览器能访问的完整入口，例如 http://服务器IP:8088 或 https://preview.example.com。决定分享链接、样例和 SDK 返回地址；不填写时根据当前请求推导。
`LICENSE_FILE`	`license.dat`	服务商签发的机器授权文件。绑定网卡 MAC 和截止时间，启动及运行时校验；到期后取得新文件替换并重启。更换服务器需重新授权。
`DATA_DIR`	data	缓存、上传文件和分享规则的保存目录。相对路径以安装目录为基准，默认在安装目录下的 data；修改目录需同时保证运行账号有写入权限。Linux 自定义目录还需更新服务文件的可写目录配置。
`KEY`	空	服务接口密钥，建议客户上线前设置足够长的随机值。业务后端创建预览时传 X-Preview-Key 请求头（也兼容 Bearer 或请求中的 key），不可把密钥写到网页或公开 SDK。签发的分享链接无需暴露密钥。官网内置示例可公开体验，不能借此预览任意源文件。
`ALLOWED_HOSTS`	空	允许下载源文件的域名列表，用英文逗号分隔，例如 files.example.com,bucket.oss-cn-hangzhou.aliyuncs.com。留空允许合法公网域名；只填域名，不含协议、路径、端口，不支持 *.example.com 通配符。内网地址仍受安全限制。
`ALLOWED_IPS`	空	访问本服务的客户端 IP 白名单，不是源文件 IP。留空允许所有客户端；配置后只允许列出的 IPv4/IPv6 地址，多个用英文逗号分隔，不支持域名或 CIDR。对所有页面、接口、资源及健康检查生效；若需本机健康检查和维护，请按需加入 127.0.0.1 和 ::1。例如 198.51.100.7,2001:db8::7,127.0.0.1,::1。
`TRUSTED_PROXIES`	127.0.0.1,::1	允许提供客户端 IP 的代理地址，可填 IP 或 CIDR，多个用逗号分隔；只有来自这些代理的 X-Real-IP/X-Forwarded-For 才被采用。留空禁用代理头信任。Nginx 应覆盖 X-Real-IP 为 $remote_addr；不要把不受控客户端网段设为受信任代理。
`CACHE_ENABLED`	true	是否复用转换结果、静态 HTML 和浏览器内容缓存。false 会增加重复转换开销；不改变分享链接的密码、权限或有效期。
`CACHE_TTL_HOURS`	168（7天）	转换缓存生命周期，整数 1–720 小时。改成 24 为一天，168 为七天。影响新生成缓存；原任务到期后再生成使用新值。缓存到期不等于业务分享链接到期。
`CACHE_MAX_MB`	2048	已完成转换缓存容量上限，单位 MB，整数 1–1048576。达到容量上限可能提前淘汰缓存，七天并不保证一直保留。处理中间文件及上传源文件会额外占用磁盘。
`MAX_FILE_MB`	50	单个源文件下载与上传的大小上限，单位 MB，整数 1–1048576。提高此项也需要足够内存、磁盘与转换时间。
`WORKERS`	1	并行转换任务数，取值 1–8。推荐配置保持 1。
`QUEUE_SIZE`	16	等待转换的任务上限，整数 1–1000。队列满时拒绝新增任务，不会无限堆积。
`JOB_TIMEOUT_SECONDS`	600	单个任务转换超时，整数 1–1800 秒。大型 PPT 分批转换仍受总超时限制；增大超时不能解决内存不足。
`FRAME_ANCESTORS`	*	允许哪些业务网页通过 iframe 嵌入预览。* 为所有来源；可填写 self（需写成单引号包裹的 CSP 关键字）及 https://业务域名，以空格分隔。不是源文件域名白名单；不要写换行或分号。

缓存默认保留 7 天，可修改 CACHE_TTL_HOURS。上传源文件保留 24 小时；业务预览链接的有效期由接口参数单独设置。

转换组件路径与其他配置

参数	默认值 / 示例	用途
`DEMO_DIR`	`demo`	官网和在线体验的自有示例目录。随安装包交付；更换位置时同步此项。
`OFFICE_ENGINE`	`libreoffice`	使用随包 LibreOffice。可选 auto、libreoffice、msoffice、wps；微软 Office/WPS 仅支持 Windows 登录用户会话。
`LIBREOFFICE_BIN`	`runtime/libreoffice/program/soffice.com`	Office 文档转换程序路径。Word、PPT 的精准模式和图片模式均需要它。
`JAVA_BIN`	`runtime/java/bin/java.exe`	Java 17 运行程序路径。OFD、TIFF、多帧 DICOM 转 PDF 时按需调用；无需启动单独的 Java 服务，不依赖 Python。
`OFD_JAR`	`converters/ofd/target/ofd-helper.jar`	OFD/TIFF/DICOM 转换组件完整路径或相对路径。安装包已包含转换组件，保持默认路径即可。
`PAGE_IMAGES_ENABLED`	true	为 PDF 和 Office 文件生成逐页图片，供图片模式、演示及缩略图使用。保持 true。
`PDFINFO_BIN`	`runtime/poppler/Library/bin/pdfinfo.exe`	Poppler 页数检查工具路径。转换完成后读取 PDF 页数。
`PDFTOPPM_BIN`	`runtime/poppler/Library/bin/pdftoppm.exe`	Poppler 页图生成工具路径。PDF/Office 图片模式及演示所用逐页 JPEG 由此生成。
`QPDF_BIN`	`runtime/qpdf/bin/qpdf.exe`	精简单页 PDF、裁剪试读页和合并大型 PPT 分批结果。缺少时部分精准阅读会回退到完整 PDF；大型 PPT 合并和试读可能无法完成。

域名与 HTTPS

直接访问使用 http://服务器IP:8088。如使用域名与 HTTPS，将域名解析至服务器，由 Nginx 或现有网关转发到本服务的 8088 端口。

配置 PUBLIC_BASE_URL=https://preview.example.com 并重启；代理需保留 Host 和 X-Forwarded-Proto。业务网页的域名如使用 HTTPS，预览入口也应使用 HTTPS。

Go 服务端口由 LISTEN_ADDR 指定，可改为其他空闲端口；同时修改对外地址及安全组、防火墙规则。本服务默认使用 8088。