title: WPS 私有化构建与部署 date: 2026-08-27 tags:

WPS
私有化
构建
部署 status: active

WPS 私有化构建与部署

1. 最快构建

在aippt-frontend-addin根目录执行：

pnpm run build:private -- https://abc.com

https://abc.com是私有化部署域名。示例：

pnpm run build:private -- http://privateweb.wxbjq.top

需要Node.js 22.x，依赖明细见 3. 构建依赖。

产物位置：dist/private-YYYYMMDD-HHMMSS/目录和同名总ZIP，包含offline.zip、online.zip、admin-private.zip、wps-com.zip、publish.html、BUILD_INFO.txt、SHA256SUMS。目录明细见 6. 输出目录。

成功判定：构建无报错结束，上述目录和总ZIP生成且七个文件齐全。交付和部署验证统一使用 12. 交付检查单。

构建或部署失败查 10. 常见失败。

2. 可选参数

pnpm run build:private -- https://example.com \
  --api-base=/aippt/api \
  --plugin-base=https://example.com/aippt-plugin \
  --wps-com-base=https://example.com/aippt-plugin/wps-com \
  --website-host=https://example.com/plugin

参数	用途
第一个位置参数	私有化主域名
`--api-base`	API前缀或完整API地址
`--plugin-base`	在线业务页面目录
`--wps-com-base`	WPS加载项目录
`--website-host`	官网或插件站点地址

参数写入：

scripts/private-deploy-config.json

当前仓库配置：

host: http://ppt-ai.sscctest.com
apiBaseUrl: /aippt/api
pluginBaseUrl: http://ppt-ai.sscctest.com/aippt-plugin
wpsComBaseUrl: http://ppt-ai.sscctest.com/aippt-plugin/wps-com
websiteHost: http://ppt-ai.sscctest.com/plugin

3. 构建依赖

依赖	要求
Node.js	22.x
pnpm	Workspace可用版本
npm/npx	`wpsjs publish`
ZIP工具	Node脚本内置依赖
网络	安装依赖和访问构建期资源

安装依赖：

pnpm install --frozen-lockfile

检查：

node --version
pnpm --version

4. 构建顺序

入口：

scripts/build-private-production.mjs

顺序：

set-private-domain.mjs写入域名；
构建offline页面；
构建online页面；
构建admin-private；
把offline.zip解压到wps-com/public/offline；
删除旧wps-com.zip；
生成publish.html；
Vite构建wps-com；
检查域名占位符和ZIP结构；
写入BUILD_INFO和SHA256SUMS；
生成总交付ZIP。

5. 子包命令

offline页面

BUILD_TARGET_ENV=offline \
pnpm --filter aippt-plugin-webview build:offline

online页面

BUILD_TARGET_ENV=online \
pnpm --filter aippt-plugin-webview build:online

WPS加载项

pnpm --filter aippt-plugin-wps-com publish:html
pnpm --filter aippt-plugin-wps-com build:vite

私有化后台

由根构建脚本调用aippt-plugin-admin-private的生产构建。

6. 输出目录

dist/private-YYYYMMDD-HHMMSS/
├── offline.zip
├── online.zip
├── admin-private.zip
├── wps-com.zip
├── publish.html
├── BUILD_INFO.txt
└── SHA256SUMS

外层：

dist/private-YYYYMMDD-HHMMSS.zip

后端或实施人员通常只需要总ZIP和SHA256校验值。

7. 部署路径

以https://example.com为例：

产物	解压位置
`online.zip`	`/aippt-plugin/`
`admin-private.zip`	`/aippt-plugin/adminPrivate/`
`wps-com.zip`	`/aippt-plugin/wps-com/`
`publish.html`	用户可访问的注册页

反向代理：

/aippt/api
→ 私有化后端API

静态服务必须正确返回HTML、JS、CSS、SVG、PNG、JSON和ZIP所需MIME类型。

8. SHA256校验

构建目录自带：

SHA256SUMS

部署前后计算SHA256，确认文件没有在传输中损坏。

9. 构建验证记录（2026-08-27）

构建环境：

Node 22.22.2
pnpm 11.9.0
host http://ppt-ai.sscctest.com

执行命令：

pnpm run build:private -- http://ppt-ai.sscctest.com

结果：构建成功。

dist/private-20260827-172834/
dist/private-20260827-172834.zip

交付文件：

文件	大小
`offline.zip`	7.1 MB
`online.zip`	7.2 MB
`admin-private.zip`	6.1 MB
`wps-com.zip`	7.6 MB
`publish.html`	44.6 KB
`BUILD_INFO.txt`	883 B
`SHA256SUMS`	396 B

SHA256SUMS中的五项全部校验通过。总ZIP：

SHA256 03fa395c66dc93ca9f7d0cbcdaaead39aa46d9b82902a13034a3ed625eb3ab80

四个子ZIP和总ZIP执行unzip -t，均通过。条目数：

offline.zip 329
online.zip 294
admin-private.zip 301
wps-com.zip 741

按文件名扫描.env、私钥、凭据和SSH部署配置，未发现这些文件进入交付包。

publish.html注册地址：

http://ppt-ai.sscctest.com/aippt-plugin/wps-com/

发现的问题：

当前终端默认Node为24.16.0，不符合.nvmrc的22.22.2；切换到Node 22后构建成功。
pnpm安装阶段提示aippt-plugin-cli/bin/cli.js缺失，导致apc软链接创建失败；不影响本次构建，但pnpm deploy可能不可用。
BUILD_INFO.txt记录Git working tree: dirty，该产物不能作为可复现的正式发布基线。
admin-private.zip包含大量.js.map源映射。生产环境不需要调试源码时应关闭source map。
当前部署域名使用HTTP。生产环境应切换HTTPS，否则固定用户密码、Token和页面资源可能被中间人读取。
BUILD_INFO.txt只写了online和admin-private的解压说明，没有写wps-com.zip的目标父目录，实施时容易多解压一层。
总ZIP没有写入目录内的SHA256SUMS，需要在交付系统中单独记录总ZIP哈希。

本次只执行构建和本地校验，没有上传服务器，也没有执行WPS客户端注册。

10. 常见失败

错误	检查
Node版本不符	使用Node 22
pnpm找不到包	在仓库根目录执行`pnpm install`
offline.zip缺失	`BUILD_TARGET_ENV=offline`和webpack日志
WPS页面404	offline资源是否并入wps-com
Ribbon URL还是占位符	`private-deploy-config.json`和Vite注入插件
publish.html地址错误	`WPS_PUBLISH_SERVER_URL`和wpsComBaseUrl
WPS注册失败	自定义协议和本地Relay
API 401	固定用户登录和反向代理
页面跨域	API CORS、Cookie和Authorization头
adminPrivate空白	PUBLIC_PATH和静态部署目录

11. 安全项

不把生产密码写入conf/sshUploadAndUnzip.yml；
使用SSH密钥或CI Secret；
固定用户使用最小权限；
publish.html只注册受信任的wpsComBaseUrl；
生产环境使用HTTPS；
保留BUILD_INFO.txt和SHA256SUMS；
部署前检查ZIP中没有源码、.env和凭据。

12. 交付检查单

交付和部署验证以本表为准，其他章节的检查项均指向这里。

检查项	方法
`offline.zip`、`online.zip`、`admin-private.zip`、`wps-com.zip`、`publish.html`、`BUILD_INFO.txt`、`SHA256SUMS`存在	查看`dist/private-YYYYMMDD-HHMMSS/`
域名占位符已替换	产物中不应出现`__PLUGIN_BASE_URL__`、`__WEBSITE_HOST__`、`privateapi.wxbjq.top`、`localhost`，除非这些值就是目标环境配置
wps-com ZIP没有重复目录	`wps-com.zip`包含顶层`wps-com/`目录，解压后应得到`<pluginBase目录>/wps-com/`；不要解压进已存在的`wps-com/`，否则会得到`wps-com/wps-com/`
manifest.xml和ribbon.xml可访问	直接访问`<wpsComBaseUrl>/manifest.xml`和`<wpsComBaseUrl>/ribbon.xml`
静态页面可访问	直接访问`<wpsComBaseUrl>/offline/about.html`、`<pluginBaseUrl>/ai-agent.html`、`<pluginBaseUrl>/template-source-lib.html`
publish.html能唤起WPS	serverUrl指向`<wpsComBaseUrl>/`，注册步骤见 WPS插件注册流程
固定用户能登录	验证方式见 WPS私有化登录流程
AiPPT和模板页面能访问API	打开AiPPT或模板页面发起一次请求

AiPPT 插件文档

探索