JXStar Template Lab

JXStar Template Lab 是一个用于把 Excel / HTML 报表模板转换成 JXStar 平台可用 .htm 模板的小工具。

它主要解决旧版 JXStar 项目里 Excel 2003 风格 HTML 报表模板不好维护的问题。上传模板后，工具会自动处理编码、脚本引用、纸张参数、图片资源目录，并输出可以直接放到 JXStar report/html 目录里的文件。

主要功能

• 支持上传 .xls、.xlsx、.htm、.html 模板。
• 支持多文件拖入和批量处理。
• 支持 LibreOffice、本机 Microsoft Excel COM、远程 Windows Excel Worker 三种转换方式。
• 支持指定 Excel 发布区域，例如 A1:O15，用于模拟 Excel 另存网页时的“选择区域”。
• 自动统一 HTML 编码为 utf-8。
• 可自动注入 JXStar 打印脚本：

<script language="JavaScript" src="../../../public/core/JxReport.js"></script>
<script language="JavaScript" src="../report.jsp"></script>

• 支持设置或保留 @page 纸张、横竖向、自定义尺寸、页边距、缩放比例。
• 支持内容居中或左上角对齐。
• 支持把 Excel 内部图片等资源整理到 模板名.files/ 目录。
• 支持浏览器预览处理后的 HTML。
• 支持下载单个 .htm，也支持下载包含 .htm 和 .files/ 的 .zip。
• SQLite 保存转换记录，默认保留 14 天。
• 提供 HTTP API、OpenAPI JSON 和可选 MCP Adapter。

推荐架构

浏览器 / MCP 客户端
    |
    v
Linux 主服务
  - React 前端
  - Rust API
  - SQLite 任务记录
  - JXStar HTML 后处理
  - 预览和下载
    |
    v
Windows Excel Worker
  - Microsoft Excel COM
  - 生成接近 Excel 2003 的 HTML

当前页面默认使用 远程 Windows Excel Worker，因为很多老式 JXStar 报表对 Excel 2003 导出的 HTML 结构比较敏感，用 Microsoft Excel 转出来的行高、图片、选择区域、资源目录通常更接近原模板。

如果没有配置 Windows Worker，可以在页面或 API 参数中手动选择 LibreOffice。

使用方法

打开工具页面：

https://jxlab.aacup.org

基本流程：

1. 把 Excel / HTML 模板拖入上传区域，或点击上传按钮选择文件。
2. 按需要调整转换参数，例如纸张、页边距、脚本路径、对齐方式、缩放比例、Excel 发布区域。
3. 上传后在中间区域预览处理结果。
4. 点击 HTML 下载单个模板文件，或点击 ZIP 下载模板和资源目录。
5. 把导出的文件放到 JXStar 项目的报表模板目录。

示例目录：

report/html/sales/form_sales_order.htm
report/html/sales/form_sales_order.files/

如果模板中有图片，.files/ 目录必须和 .htm 文件放在同一级目录。

浏览器里的 @page 只能建议纸张和边距；真实打印时，目标打印机、纸张、DPI、驱动纸张大小仍然需要在浏览器打印面板里选择正确。

转换内核

远程 Windows Excel Worker

生产环境推荐使用这种方式。

Linux 主服务负责页面、API、SQLite、JXStar HTML 后处理和下载；Windows Worker 只负责调用本机 Microsoft Excel COM，把 Excel 文件发布成原始 HTML 和资源目录，再返回给 Linux 主服务继续处理。

适合需要尽量还原 Excel 2003 HTML 输出的模板。

本机 Microsoft Excel

适合整个服务直接跑在 Windows 上，并且机器里已经安装 Microsoft Excel 的场景。

这种方式也通过 Excel COM 生成 HTML，但不适合 Linux Docker 容器。

LibreOffice

适合纯 Linux / Docker 环境，部署简单，可以作为兜底方案。

但 LibreOffice 导出的 HTML 和 Excel 2003 不是完全一致，部分模板可能出现图片位置、行高、单元格边框、选择区域、VML 数据等细节差异。

Docker 部署

生产环境建议主服务只监听本机端口，再通过 1Panel / Nginx / Caddy 反向代理提供 HTTPS 域名：

APP_PORT=127.0.0.1:52400

从源码本地构建：

cp .env.example .env
docker compose up -d --build

使用已构建镜像部署：

mkdir -p /opt/jxstar-template-lab
cd /opt/jxstar-template-lab
cp /path/to/deploy/docker-compose.prod.yml docker-compose.yml
cp /path/to/deploy/server.env.example .env
docker login git.aacup.org
docker compose pull
docker compose up -d

检查服务：

curl http://127.0.0.1:52400/api/health
docker compose logs -f --tail=100

更多部署说明见：

deploy/README.md

Windows Excel Worker

生成 Windows Worker 安装包：

powershell -ExecutionPolicy Bypass -File scripts/package-windows-worker.ps1

Docker 镜像也会在站点根路径发布同一个安装包：

https://jxlab.aacup.org/jxstar-excel-worker-windows.zip

在 Windows Server 上解压安装包，然后用管理员 PowerShell 执行：

cd 解压目录
Set-ExecutionPolicy -Scope Process Bypass -Force
.\install.ps1 -AllowedIp Linux主服务IP

安装脚本会创建 C:\JxstarExcelWorker，必要时安装 Node.js 16，配置防火墙规则，创建桌面启动快捷方式，并输出：

REMOTE_EXCEL_WORKER_URL=http://<WindowsServerIP>:52401
REMOTE_EXCEL_WORKER_TOKEN=...

把这两项填入 Linux 主服务的 .env，然后重启主服务：

docker compose up -d

Worker 健康检查：

curl http://127.0.0.1:52401/health

更新已安装的 Worker：

cd 新包解压目录
Set-ExecutionPolicy -Scope Process Bypass -Force
.\update.ps1 -Restart

update.ps1 会保留 C:\JxstarExcelWorker\.env.cmd，不会重新生成端口和 token。

安装包里也带有 quick-update.cmd，它默认从下面地址下载最新安装包并自动更新：

https://jxlab.aacup.org/jxstar-excel-worker-windows.zip

如果部署在其他域名，可以把下载地址作为第一个参数传进去：

quick-update.cmd https://your-domain/jxstar-excel-worker-windows.zip

Forgejo / Gitea Actions

自动构建部署配置在：

.gitea/workflows/docker-deploy.yml

推送 main、master 或 v* tag 时，会自动构建 Docker 镜像并推送到镜像仓库。

需要配置仓库变量：

DOCKER_REGISTRY=git.aacup.org

需要配置仓库密钥：

REGISTRY_USERNAME
REGISTRY_PASSWORD

如果希望推送后自动部署到服务器，还需要配置：

DEPLOY_HOST
DEPLOY_USER
DEPLOY_PORT
DEPLOY_SSH_KEY

配置了 DEPLOY_HOST 后，workflow 会连接服务器，准备 /opt/jxstar-template-lab，首次部署时自动创建 docker-compose.yml 和最小 .env，然后执行：

docker compose pull
docker compose up -d

首次部署后，需要到服务器上编辑：

/opt/jxstar-template-lab/.env

至少填好：

PUBLIC_BASE_URL
REMOTE_EXCEL_WORKER_URL
REMOTE_EXCEL_WORKER_TOKEN

API 和 MCP

OpenAPI 地址：

GET /api/openapi.json

启动 MCP Adapter：

cd mcp
npm install
JXSTAR_TEMPLATE_LAB_URL=https://jxlab.aacup.org npm start

MCP 配置示例：

{
  "mcpServers": {
    "jxstar-template-lab": {
      "command": "node",
      "args": ["D:/Jxstar_Projects/app/jxstar-template-lab/mcp/server.mjs"],
      "env": {
        "JXSTAR_TEMPLATE_LAB_URL": "https://jxlab.aacup.org"
      }
    }
  }
}

API 调用示例见：

docs/api.md

环境变量

变量	默认值	说明
APP_BIND	0.0.0.0:8088	容器内 Rust API 监听地址
APP_PORT	127.0.0.1:52400	Docker 映射到宿主机的端口
APP_DATA_DIR	/app/data	数据目录
DATABASE_URL	sqlite:///app/data/jxstar_template_lab.db?mode=rwc	SQLite 数据库地址
FRONTEND_DIR	/app/frontend/dist	前端构建目录
WORKER_SCRIPT	/app/worker/convert.mjs	Node 转换脚本路径
PUBLIC_BASE_URL	空	生成绝对下载链接时使用的外部访问地址
MAX_UPLOAD_BYTES	52428800	单个文件上传大小限制，默认 50 MB
RETENTION_DAYS	14	上传文件和转换记录保留天数
CONVERSION_TIMEOUT_SECS	180	主服务单次转换超时时间
EXCEL_COM_TIMEOUT_MS	120000	Windows Excel COM 转换超时时间，单位毫秒
SOFFICE_BIN	soffice	LibreOffice 可执行文件
CONVERSION_ENGINE	remote-excel	没有传入请求参数时使用的默认转换内核
REMOTE_EXCEL_WORKER_URL	空	远程 Windows Worker 地址
REMOTE_EXCEL_WORKER_TOKEN	空	远程 Windows Worker Bearer Token
IMAGE	git.aacup.org/cosmo/jxstar-template-lab:latest	生产部署使用的 Docker 镜像

许可证

MIT License