GoScan Twink 多模态知识库 · 安装部署与应用 SOP

1产品简介（方案演示）

下方为系统的产品方案交互演示（通用行业版），可点击翻页查看产品能力与场景方案。演示内容已随本交付包离线集成（本地 intro.html），无需联网、不依赖任何公网地址。

📎 产品方案演示已随本交付包一同提供（intro.html）。请用浏览器打开本包根目录下的「启动本地预览」脚本，或双击 intro.html 查看交互演示。

说明上方为「通用行业版」产品方案交互演示，内容已本地集成，完全离线可用。演示为自包含单文件（intro.html），可用左右按钮 / 方向键 / 滑动翻页查看；如需增加「工业制造场景版」，将对应的本地单文件放入本包并替换 iframe 地址即可。

系统一句话定位

GoScan Twink 是一款面向企业的多模态知识库：以"多账号 + 层级文件夹 + 全文检索 + AI 智能体"为核心，统一管理文档 / 图片 / 音视频 / Office / 3D 模型等多类型资料，支持在线预览、系统内共享、外链分享与 AI 知识问答，可私有化部署于客户自有服务器。

2安装部署 SOP

以下流程基于 Node.js + Express 后端、better-sqlite3 单文件数据库、PM2 进程守护。标准交付形态为 cloud-share-platform-*.zip 安装包 + update.sh 平滑更新脚本。

2.1 环境要求

项目	最低要求 / 推荐
操作系统	Linux（CentOS 7+ / Ubuntu 20.04+ 推荐）；亦支持 Windows Server（用 PM2 或 nssm 守护）
Node.js	≥ 18（推荐 18 LTS / 20 LTS）。better-sqlite3 需匹配 Node 版本的预编译包
内存	≥ 2 GB；进程内存上限 512 MB，含对象存储预览缓存建议 4 GB+
磁盘	系统盘 ≥ 20 GB；文件存储建议独立挂载（对象存储或数据盘）
端口	默认 `3000`（可用环境变量 `PORT` 修改）
依赖	PM2（`npm i -g pm2`）；如需对象存储挂载需 FUSE 支持

2.2 获取并解压安装包

上传安装包到服务器项目目录（建议 /root/cloud-share-platform/）。安装包已排除 node_modules / data / uploads / .env，体积小、传输快。

# 登录服务器后 mkdir -p /root/cloud-share-platform cd /root/cloud-share-platform # 用 scp / 宝塔 / 对象存储将 cloud-share-platform-*.zip 上传到此处 unzip -o cloud-share-platform-*.zip

安装运行依赖（仅需首次）：

cd /root/cloud-share-platform npm install --production --no-audit --no-fund

better-sqlite3 会在安装时拉取与当前 Node 版本匹配的预编译包，请保持 Node ≥ 18。

2.3 基础配置（环境变量）

配置二选一：① 直接改 ecosystem.config.js 的 env 块；② 在项目根目录新建 .env（lib/env.js 会自动加载）。推荐用 .env，便于与代码分离、安全留存。

# /root/cloud-share-platform/.env PORT=3000 NODE_ENV=production STORAGE_DIR=/mnt/cos-data # 文件物理落盘目录；不配则默认项目内 uploads/ CACHE_SIZE_GB=4 # 本地预览缓存上限(GB)，0=关闭 SESSION_SECRET=请换成随机长字符串 # ⚠ 务必修改，否则有安全风险 ADMIN_PASSWORD=请换成强密码 # ⚠ 初始管理员密码，默认 admin123

变量	默认	说明
PORT	3000	服务监听端口
STORAGE_DIR	项目内 uploads/	上传文件物理落盘目录，建议指向对象存储本地挂载点
CACHE_SIZE_GB	4	预览缓存上限；超上限按 LRU 淘汰；0=关闭缓存
SESSION_SECRET	内置占位值	会话签名密钥，生产必须修改
ADMIN_PASSWORD	admin123	首次启动自动创建的内置管理员密码，必须修改

安全SESSION_SECRET 与 ADMIN_PASSWORD 出厂为占位/弱口令，上线前务必修改，否则存在越权与数据泄露风险。

2.4 启动服务（PM2）

用 ecosystem 配置启动（务必用此方式，保证环境变量生效）：

pm2 start ecosystem.config.js pm2 save

⚠ 不要用 pm2 start server.js —— 那样会丢失 env / .env 中的环境变量。

配置开机自启：

pm2 startup # 按提示执行输出的命令 pm2 save

验证服务：管理后台对外访问地址 http://<服务器地址或域名>/GoScanTwinK/app（内部服务仍运行在 :3000，经反向代理以 /GoScanTwinK/ 路径前缀对外提供）

curl -sf http://<服务器地址或域名>/GoScanTwinK/app -o /dev/null && echo "服务正常" # 服务器本地自检可用内部地址：curl -sf http://127.0.0.1:3000/app

首次启动会自动初始化数据库 data/knowledge.db 并创建管理员 admin / 上述密码。

2.5 反向代理与域名（以宝塔为例）

添加站点：宝塔 → 网站 → 添加站点，填写客户域名（如 kb.example.com），PHP 纯静态即可。

配置反向代理：站点设置 → 反向代理 → 添加代理；
目标 URL http://127.0.0.1:3000，发送域名填 $host。

关闭缓存：在该站点反向代理设置中关闭缓存，避免后台操作被缓存。

Nginx 直配等效写法：

location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; }

2.6 HTTPS / SSL 证书

部署证书：宝塔 → 站点 → SSL → 选择证书（TrustAsia / Let's Encrypt 均可）→ 部署。

强制 HTTPS：开启"强制 HTTPS"，并将 https://域名 作为系统正式访问地址告知客户。

说明Office 文档在线预览依赖公网 HTTPS 访问；若仅内网使用，预览将回退为"下载原件"。

2.7 对象存储挂载（可选，goosefs-lite / FUSE）

如客户使用对象存储做统一文件底座，可将存储挂载到 /mnt/cos-data，实现"代码与数据分离、文件不落本地系统盘"。

挂载对象存储到 /mnt/cos-data（按客户存储产品文档操作 FUSE 挂载，确保可写）。

设置落盘目录：在 .env 设 STORAGE_DIR=/mnt/cos-data，再 pm2 start ecosystem.config.js --update-env。

验证：上传一个文件，确认 /mnt/cos-data/files/ 下出现新文件；预览读写经本地缓存 data/cache/files 加速。

兼容对象存储 FUSE 不支持追加写 / copy_file_range 等，系统已内置 copyToStorage 顺序写流封装，无需手动处理写入兼容性。

2.8 升级与平滑更新（update.sh）

上传新版 zip到项目根目录 /root/cloud-share-platform/（与 update.sh 同级）。

执行更新：

cd /root/cloud-share-platform bash update.sh # 自动查找最新 zip；或显式：bash update.sh /path/to/xxx.zip

脚本自动完成：备份当前代码 → 解压覆盖（保留 data/ uploads/ node_modules/ .env）→ 同步依赖 → 平滑 reload（含环境变量双检查 + 失败降级 delete+start）→ 健康检查。

回滚（如更新异常）：

cp -r backup-时间戳/* . && pm2 reload knowledge-base

0 停机更新过程为平滑 reload，用户无感知；脚本保留最近 3 份代码备份便于回滚。

2.9 健康检查与排错

检查项	命令 / 位置
端口与后台可达	对外：`curl -sf http://<服务器地址或域名>/GoScanTwinK/app` 返回 200（内部自检：`curl -sf http://127.0.0.1:3000/app`）
进程状态	`pm2 list` / `pm2 describe knowledge-base`
运行日志	`pm2 logs knowledge-base` 或 `logs/pm2-out.log`
环境变量生效	`pm2 env 0 \| grep -E "STORAGE_DIR\|CACHE_SIZE_GB"`
数据库只读报错	多为 `data/` 权限问题，`chown -R 当前用户 data uploads` 后 reload

3应用 SOP（管理后台使用）

以下为系统管理员与最终用户的高频操作。完整说明可在系统「设置 → 帮助与操作说明」中随时查阅。

3.1 登录与界面

浏览器打开管理后台（如 https://kb.example.com/app），输入账号密码登录。

主界面：左侧边栏切换「主页 / 资源管理 / 最佳实践 / 账号管理」；左下角头像菜单含设置、外观、帮助、退出登录；顶部操作栏含上传、新建文件夹、全局搜索。

主题与语言：头像 → 设置 → 外观，可切「亮色 / 暗色 / 跟随系统」；同面板语言区可切「中文 / English」，自动保存。

3.2 账号与权限

角色	权限范围
超级管理员	全部设置、账号管理、系统配额、硬盘信息
部门管理员	创建普通用户、分配配额、监管下级文件、部分设置
普通用户	管理自己的文件、预览、分享、个人中心

创建子账号：账号管理 → 新建账号 → 填写用户名 / 密码 / 角色与层级 / 存储配额 / 公司部门 / 手机邮箱 / 头像 → 保存。

注意超级管理员账号不可降级、不可停用；停用其他账号后其文件保留。

3.3 文件管理

上传：进入目标文件夹 → 上传文件 → 多选并填标题 / 描述 / 标签 → 开始上传（自动分片、断点续传；内容相同的文件自动秒传）。
文件夹：新建 / 重命名 / 移动 / 删除，均通过文件卡片「更多」菜单操作。
预览：点击卡片缩略图或标题即可在线预览（图片、视频、PDF、Office、3D 模型均支持）。
搜索：顶部搜索框输入关键词（标题 / 描述 / 标签 / 文档正文）；主页可输入自然语言问题，由 AI 检索并综合回答、注明引用来源。

3.4 文件夹共享（系统内）

文件夹「更多 → 共享」，选择共享范围：指定用户 / 公共区域 / 同级用户 / 上级用户，可勾选「包含子文件夹」。

选择权限：只读（可浏览 / 下载）或读写（可改 / 删 / 移）。默认只读，防误改。

便利共享文件夹后，内部文件一并共享，无需逐个共享；被共享人刷新后在「资源管理」看到该文件夹。

3.5 外部分享（链接 / 口令 / 水印）

点击文件 / 文件夹「分享」→ 复制分享链接或扫码。

可设访问口令与过期时间；分享页支持水印叠加与禁用右键复制，增强版权保护。

「允许下载」关闭后，预览页隐藏下载按钮，仅在线查看。

3.6 设置（外观 / 语言 / AI 助手）

个人中心：改头像、公司 / 部门 / 手机 / 邮箱、改密码、查看存储用量。
系统设置（超管）：存储管理、登录安全、登录界面主题（3D 地球 / 知识图谱，可实时预览）、AI 知识助手配置。
AI 知识助手（可选）：设置 → 系统设置 → AI 配置，填入服务商 / API Key / 模型并开启；支持 DeepSeek、OpenAI、通义千问、本地 Ollama。文件「AI 总结」与右下角知识库问答即用。

3.7 移动端适配

侧边栏在窄屏变为抽屉式（左上角 ☰ 打开），文件网格自动调整列数，弹窗接近全屏，设置分区横向排列。手机浏览器访问同一地址即可获得一致体验，无需单独 App。

4常见问题（FAQ）

Q1：上传大文件失败？

确认账号上传大小限制；检查网络后重试，系统支持断点续传；若使用对象存储，确认 FUSE 挂载可写。

Q2：Office 文档无法在线预览？

在线预览需文件可通过公网 HTTPS 访问；如不可达，可点「下载原件」在本地打开。确认 SSL 已部署且域名可公网解析。

Q3：视频没有封面？

首次在网格查看会自动截取第 1 秒作封面；已上传视频不会补生成，可重新上传。

Q4：共享文件夹后别人看不到里面文件？

确认共享时勾选「包含子文件夹」或文件确在该文件夹内；默认只读，接收方刷新后在「资源管理」可见。

Q5：只想让别人看、不想让他改？

共享权限选「只读」；只读状态下接收方无法重命名 / 移动 / 删除或再次共享该文件夹。

Q6：部门管理员看不到部分设置？

部门管理员仅可见外观 / 语言 / 个人中心 / 存储用量；AI 配置、登录安全、存储管理等仅超管可见。

Q7：存储空间不足？

在「设置 → 个人中心」查看已用空间；联系超管提高配额，或扩容存储 / 对象存储。

Q8：忘记管理员密码？

超管可在服务器用 ADMIN_PASSWORD 重置（改 .env 后 reload），或经数据库直接更新 users 表密码哈希。

5技术支持与交付清单

交付清单

物料	说明
`cloud-share-platform-*.zip`	系统安装包（已排除 node_modules / data / uploads / .env）
`update.sh`	平滑更新脚本（备份 / 覆盖 / 重载 / 健康检查）
`ecosystem.config.js`	PM2 启动与环境变量配置
`docs/`	产品操作说明等文档（系统内「帮助」可直接查看）
产品方案演示	在线交互演示（通用行业 / 工业制造两套场景）

部署服务支持

首次部署协助：环境检查、安装启动、反向代理与 SSL、初始账号交接。
版本升级：提供新版 zip + 更新指引，支持平滑 0 停机更新与回滚。
对象存储对接：协助 FUSE 挂载与落盘目录配置。
AI 助手接入：协助配置大模型服务商与密钥。

联系部署与运维问题请联系实施负责人；系统使用问题可在系统内「设置 → 帮助与操作说明」自查。