# 瀚境科技产品库 · Ubuntu 24.04 部署说明

这份部署包已经构建，服务器不需要 npm、编译、Docker 或宝塔。运行环境为 Node.js 24 LTS + SQLite + 私有磁盘文件存储；同一套产品/账号 API 继续校验六种角色权限。只在新服务器上安装，先保留原网站。

## 1. 准备两个文件

- `hanjing-ubuntu.tar.gz`：程序部署包，**不包含真实产品、图片、员工密码或云服务密钥**。
- 管理员在原网站“数据备份 → 一键导出全部迁移包”生成的完整 `.hjm`：包含账号密码摘要、六种角色、一次改密状态、产品与侵权库、图片、优先级、日志、导入台账、历史备份及汇率记录。必须另行记住该迁移包的加密口令。

JSON/CSV/Excel 产品备份不是全系统迁移包，不能用来迁移员工账号和权限。导出时等待“导出完成”，中断包不能导入。最终切换前通知员工暂停原站新增和修改，再导出一份最新迁移包。

## 2. 上传、安装

把部署包和 `.hjm` 通过腾讯云控制台文件上传或 SFTP 上传到 Ubuntu 用户的主目录。不要把密码、SSH 私钥或迁移口令发到聊天里。

```bash
mkdir -p ~/hanjing-installer
tar -xzf ~/hanjing-ubuntu.tar.gz -C ~/hanjing-installer
cd ~/hanjing-installer
sudo bash install.sh
```

安装程序会检查 Ubuntu 24.04、校验部署文件、安装 Python/Caddy，并从 Node 官方 HTTPS 地址下载带 SHA256 核对的 Node 24 LTS 二进制。新建独立 `hanjing` 服务用户，网站进程不以 root 运行；默认 Node 堆上限256MB、服务内存上限512MB。1GB 内存仅作低负载试运行，仍须结合内存、图片上传及同时使用人数验收。

安装时填写二选一：

### 有自己的域名：正式 HTTPS

先把域名 A 记录指向服务器公网 IPv4。填写 `https://你的实际域名`，不要输入 `hanjing.com`，除非它已经归你所有且已完成解析。腾讯云防火墙开放 TCP 80/443；SSH 22 尽量只允许维护者IP，不要开放8080和数据库端口。

Caddy 会申请和续期 HTTPS 证书。需要域名解析正确且80/443可达。仅购买服务器不会自动取得域名，也不会自动开通短信。此流程不依赖 ChatGPT/Google 员工登录。

### 暂时没有域名：安全试用

按回车使用 `http://localhost:8080`。在**你自己的电脑**终端运行：

```bash
ssh -N -L 8080:127.0.0.1:8080 Ubuntu用户名@服务器公网IP
```

保持终端连接，再在浏览器打开 `http://localhost:8080`。这是 SSH 加密隧道，适合先验收；不是给全体员工使用的公网网址。网站保留 Secure/HttpOnly 会话，不提供在公网 HTTP IP 上明文发送员工密码的模式。员工浏览器访问和钉钉入口，应在正式 HTTPS 配置好后验收。

**不要把整个数据目录放到网站公开目录，不要安装后重新注册一套管理员。** 尚未导入时网站显示维护提示，初始化 API 关闭。

## 3. 导入完整数据

将下方路径换成你上传的真实文件的绝对路径：

```bash
sudo hanjing import /home/ubuntu/完整迁移包.hjm
sudo hanjing verify
sudo hanjing status
```

输入的是 **迁移包加密口令**，不是云服务器密码或员工密码。输入不会回显。程序先完整解密、认证各帧、核对数据库行数、每个图片/备份文件摘要及图片引用，确认主管理员仍有效；全部通过后一次切换数据目录。错误口令、截断文件、丢失图片、较新不兼容字段会中止。初次导入只接受空目标，重复导入会拒绝，避免重复产品。导入期间维护命令会停止网站和数据任务，结束后重新启动。

原员工用原用户名和密码**重新登录**；旧浏览器登录会话、旧验证码、过期恢复凭证和云服务密钥不迁入。一次自行改密次数、密码摘要和审核原因保留。数据已经导入后不要再次初始化管理员。

## 4. 定时更新与备份

- 汇率：每天北京时间09:00抓取服务器固定供应商并保存24个币种；任务失败自动间隔75秒重试，启动限制防止无限循环；失败保留旧数据，来源日期较旧时页面明确显示上一期。服务器停机错过任务后，开机补执行一次。管理员网页仍可手动同步。
- 全系统备份：每天北京时间02:00生成加密 `.hjm`，完整解密校验通过后才算成功，默认最多保留14份。会话及验证码不在备份中。
- 本机备份位置：`/var/backups/hanjing/`。自动生成的**独立备份加密口令**在 `/etc/hanjing/backup.key`，与原迁移包口令不同。务必单独下载、保管口令文件；没有口令不能恢复。
- 本机备份不等于异地备份。未配置其他存储账号时，系统不会声称已有异地副本。至少定期下载加密备份和校验文件到另一台设备。

手动触发并看结果：

```bash
sudo hanjing exchange
sudo hanjing backup
sudo hanjing verify
sudo hanjing status
```

`Persistent=true` 不会补生成停机期间每一天的历史汇率，历史从实际成功采集开始积累。任务时间由 systemd 的 `Asia/Shanghai` 明确指定，不依赖服务器默认时区。

### 可选：自动异地备份

以后有自己的对象存储账号时，在服务器安装 `rclone`，通过它的交互配置创建仅能访问备份桶的 remote，把配置保存在 `/etc/hanjing/rclone.conf`，所有者 `root:hanjing`、权限0640。不要把对象存储密钥发到聊天或写进源码。

在 `/etc/hanjing/hanjing.env` 添加例如 `BACKUP_REMOTE=backupremote:你的桶名/hanjing`。重启备份任务后，已验证的加密包和SHA256文件会上传到该位置；上传失败会使任务失败且不清理旧备份。remote权限限定为你的备份桶，不要挂载公开图片桶充当备份。先手动 `sudo hanjing backup` 并确认日志 `"offsite": true`，再实际下载一份在空目录恢复验证。异地远端不自动清理旧文件，请在存储服务配置保留策略。

## 5. 完整恢复与回滚

```bash
sudo hanjing restore /绝对路径/要恢复的备份.hjm
sudo hanjing verify
```

输入该备份对应的口令。恢复会使网站短暂不可用并把业务数据回到备份时刻；备份后的新增修改不会出现在恢复结果中。程序校验通过才切换，恢复前的整个业务目录会保留在 `/var/lib/hanjing/retired/`，不会覆盖或自动删除。如需回滚，应停止网站和两个任务后由维护者将该目录恢复为 `active`，再检查和启动。不要在网站运行时手动替换 SQLite 文件。

请在新空目录先演练恢复，确认账号、产品和图片都能读取。数据库事务和对象文件原子写入能降低崩溃损坏风险，不保证永久不丢失；持续保留独立副本。

## 6. 管理员忘记密码

服务器所有者使用 SSH/云控制台进入后执行：

```bash
sudo hanjing reset-admin
```

本地输入两次新密码，原主管理员用户名不变，原登录会话全部失效，并记录审计。员工无法从网页调用这个命令，不消耗或重置账号“一次自行改密”标记。短信验证码找回仍需单独开通并配置阿里云短信签名、模板和密钥；未配置会如实显示不可用。

## 7. 正式网址、升级与验收

先使用试用隧道时，后续有域名后：在配置文件把 `PUBLIC_ORIGIN` 改为实际 HTTPS 域名；根据 `install.sh` 中 Caddy 示例配置反向代理（必须固定 Host，并覆盖 `X-Hanjing-Client-IP`）；开放80/443，验证证书后重启网站。也可在维护者协助下重新执行安装程序，它会保留已有配置，不能靠重新安装自动修改网址。不能直接改成HTTP公网IP。

程序更新：使用新部署包执行 `sudo bash install.sh`。原配置、备份密钥、账号和图片目录保留。旧程序版本在 `/opt/hanjing/releases/`。当前数据库模式为第1版，未来涉及数据库结构的升级需要相应迁移脚本及升级前完整备份，不能把旧程序覆盖运行到较新数据库。

切换钉钉之前，用不同角色验证：

1. 管理员可管理人员、导入、查看日志/修改记录、备份，新增产品直接通过，能改设计优先级。
2. 运营专员只读；开发专员可新增并提交；审核专员能通过/驳回，驳回必须写原因。
3. 其他角色看不到管理页面，直接请求管理 API 也被拒绝。
4. 两套产品库、图片、选品人/时间/专利/备注、侵权国家和排序、设计优先级及改密次数与原站一致。
5. 新增一条测试记录，重启网站后仍存在；完整备份能恢复到另一空目录。
6. 员工在实际网络的普通浏览器、钉钉内访问实际 HTTPS 网址；登录、上传、会话保持正常，再更新工作台链接。

本部署包不带原平台的访问防火墙，但不承诺香港线路、钉钉兼容性或第三方服务始终正常。最终仍需在你的真实 Ubuntu 服务器、域名和网络上验收。准备包和本地测试完成，不等于已经部署到你尚未提供的服务器。