# 小批发订货与对账 · 安装部署手册（1.0.0）

运行需要 Docker Engine 24+、Compose v2、2核4GB内存（推荐4核8GB）、40GB可用磁盘。Java编译目标17，运行推荐21；MySQL8.4、Redis7.4、Node22/24和pnpm11。所有业务日期按Asia/Shanghai。Java默认时区、Druid新连接和Flyway会话都显式固定+08:00；不能只依赖JDBC的serverTimezone参数，因为它不会设置MySQL NOW()/CURDATE()的会话时区。

## 1. 正式与演示分开

正式环境只装系统基础表、角色、菜单和业务参数，不安装客户/商品/订单演示数据。`APP_DEMO_DATA=false`、`APP_DEMO_RESET_ENABLED=false`、`PAY_MOCK_ENABLED=false`。客户账号须在「用户管理」建立并分配「订货客户」，再在「客户与账期」选择账号建档、审核和设置价格/账期。

演示环境 `APP_DEMO_DATA=true` 会自动迁移 `db/demo`，账户密码公开，数据虚构，不能承载真实业务。恢复双开关和保留范围见 `演示数据恢复机制.md`。不使用删库/删卷恢复。

## 2. 生成环境与启动

```bash
cd deploy
./scripts/init-env.sh
# 演示专用：./scripts/init-env.sh --demo（二选一）
docker compose config --quiet
docker compose build server
docker compose build web
docker compose up -d
docker compose ps
```

初始化生成随机数据库/Redis密码、TOKEN_SECRET和支付参数加密主密钥。`.env`权限600，不放源码包和公开网盘。管理员初始密码可留空随机生成并只打印一次，或设8至20位强密码。首次登录图形验证码后进入改密，修改前业务API返回428。严禁把dev配置部署公网。

网页端口由HTTP_PORT配置，反向代理使用HTTPS；后台`/`，H5`/h5/`，接口`/api/`。MySQL、Redis不对外暴露。生产无需在线支付，公共支付配置保留但本产品没有在线支付入口。

## 3. 首次营业配置

1. 系统设置填写真实公司名、系统名、服务电话、账号策略；设置与账号密码不随演示业务恢复清除。
2. 建销售/仓库/财务账号并分配对应角色。仓库可手机查看待发和拣货，财务独立收款核销。
3. 商品与价格建立SKU（或下载CSV模板导入），销售单位与基本单位换算明确；商品图片用页面上传，支持JPG/PNG/WebP最大5MB。已有SKU不能改单位换算，须新建SKU。
4. 库存流水按基本单位登记期初数量和原因；不从商品编辑直接改库存。
5. 建客户账号、客户档案、审核、等级/专属价、可见等级；客户自己或代客订货入口新增收货地址。
6. 订货设置核对固定运费与免运门槛；以报价确认页为准。所有价格为含税价，不另加税、不接税控开票。
7. 使用一笔测试采购走完确认、部分发货、签收、收款核销、退货和对账，核对实物及账务后再正式使用。

## 4. 备份与升级

部署内置脚本`deploy/scripts/backup.sh`和`restore.sh`。同时备份MySQL、上传目录、`.env`与PAY_CONFIG_KEY；定期在隔离环境验证恢复。升级前备份，Flyway自动执行新增迁移，不改已执行SQL。日志文件保留400天，登录和操作日志至少365天，不在业务恢复中删除。

## 5. H5、小程序和App

```bash
cd client
pnpm install --frozen-lockfile
pnpm type-check
pnpm build:h5
VITE_API_BASE=https://your-domain.example/api pnpm build:app
# 可选小程序：配置manifest小程序appid和域名后 build:mp-weixin
```

H5产物`client/dist/build/h5`由Web镜像一并部署。App构建输出uni-app资源，不等于已签名APK。APK需独立DCloud应用标识/包名/AppKey、正式签名、原生运行时，再由HBuilderX或离线SDK打包；集成任务统一处理原生打包，最终路径见交付记录。测试HTTP只允许显式`VITE_ALLOW_HTTP_API=1`，不能当正式发布配置。

App未启用uni统计，未请求通讯录/定位/相机。Android拒绝隐私说明可仅浏览企业介绍、电话和说明，不读取登录令牌、不调用私有业务接口。原生弹窗使用项目内 static/legal/privacy.html，可离线打开；正式上架前须补齐真实运营主体、联系方式、保存期限、权利渠道并核实DCloud运行时实际收集项。App登录页和“我的”可改可信HTTPS服务器，切换退出并清空草稿；H5固定同源/api，不支持此切换。

## 6. 验证

`server/scripts/smoke_wholesale.py`是仅本机隔离环境的真实API测试，会执行受控演示恢复和测试写入。须配置专用MySQL/Redis，提供私有`WH_ADMIN_FILE`与`WH_PRIVATE_RUNTIME`，不能指向正式实例。标准API处理首次改密，凭据只写权限600的私有目录。实际结果见`测试与交付记录.md`。

H5推荐与后台同源，接口使用`/api`由Nginx代理。默认CSP的connect-src限制为self，跨域API会被浏览器阻止；确需分域时必须同时配置服务端允许来源、Nginx CSP和HTTPS，不仅修改VITE_API_BASE。App没有H5同源代理，使用自有HTTPS API。

## 7. 从干净Linux主机复现与验收

先安装Docker Engine与Compose v2，检查 `docker version`、`docker compose version`；服务端和两端前端都在镜像中编译，生产主机无需额外安装Java/Node/pnpm。解压源码，进入本产品deploy目录，只运行一次init-env。已存在数据库时禁止随意重新生成DB_PASSWORD。保管.env、PAY_CONFIG_KEY和备份，不提交源码或公共下载。

正式部署用默认单文件Compose；公开演示才叠加下面专用服务器配置。选择空闲HTTP_PORT，若由同机HTTPS代理接入则设置HTTP_BIND=127.0.0.1，代理转发到该端口。MySQL和Redis保持不向公网映射。执行build/up后检查：

```bash
docker compose ps
docker compose logs --tail=100 server
# 将8080换为自己配置的HTTP_PORT；这两个请求无需登录，不打印密钥
curl --fail --silent --show-error http://127.0.0.1:8080/api/public/brand
curl --fail --silent --show-error http://127.0.0.1:8080/api/public/wholesale/info
```

浏览器打开后台，使用初始化时仅显示一次的管理员密码和图形验证码，完成首次改密再配置品牌、角色、客户、商品、库存和运费。正式配置的商品/订单/演示账号应为零；以自己的测试客户跑通报价、部分发货、收款核销和对账后营业。HTTPS域名下再检查后台、H5、API、图片附件和真实登录，不能只依据容器healthy。

## 8. 当前共享服务器演示配置（非通用正式默认值）

目标域名 `https://dh.diankit.com`；后台 `/`，H5 `/h5/`，同域API `/api/`。服务器目录 `/opt/wholesale-ordering`，Compose项目 `wholesale-ordering-demo`，仅回环 `127.0.0.1:8092` 由Caddy统一HTTPS转发。本轮线上状态以部署验收记录为准。

共享演示服务器用 `deploy/docker-compose.demo-server.yml` 叠加资源与日志配置；部署.env中设置：

```dotenv
COMPOSE_FILE=docker-compose.yml:docker-compose.demo-server.yml
COMPOSE_PROJECT_NAME=wholesale-ordering-demo
NGINX_CONF=proxy.conf
HTTP_BIND=127.0.0.1
HTTP_PORT=8092
```

也可从deploy目录显式执行 `docker compose -p wholesale-ordering-demo -f docker-compose.yml -f docker-compose.demo-server.yml up -d --build`。该overlay只适用于共享演示服务器，不应在独立客户环境无理由照搬资源上限。

公开演示由维护者额外启用双gate恢复，并配置 `APP_DEMO_RESET_CRON="0 21 4 * * *"`（Asia/Shanghai，每日04:21）。源码默认恢复和定时任务仍关闭。正式客户数据库禁止启用自动演示恢复；演示数据不能承载真实经营记录。凭据由现场私有.env管理，不记录在本文。

## 2026-10-23 当前部署记录

本产品公开演示站已完成HTTPS、管理与H5资源、角色/系统设置/业务只读接口验收；本次管理员初始化与真实备份已核对。具体隔离参数、定时恢复与验证边界见[演示站部署验收记录](deployment-20261023.md)，原生包更新要求见[构建与后续更新要求](updates.md)。不把历史UI阶段记录视为当前最终交付状态。


---
官网公开文档：已移除内部维护段落。实际部署凭据不公开；未作为网页提供的包内文档以明确路径标注。APK与演示下载状态以产品页面为准。