綦江烟草部署（在wsl2里部署）

WSL2 是什么？

WSL2 全称是 Windows Subsystem for Linux 2，中文叫"Windows 的 Linux 子系统"。

你可以把它理解成：

Windows 自己带的一个"轻量级 Linux 虚拟机"。

以前你想在 Windows 里用 Ubuntu，通常要装 VMware 或 VirtualBox，再完整装一个 Ubuntu 系统，比较重。

WSL2 不一样：

它是 Windows 自带的功能；
你可以在里面直接装 Ubuntu；
不用单独开一个虚拟机窗口；
更轻、更快，和 Windows 文件互通也方便。

所以，WSL2 可以让你在 Windows 电脑上跑 Ubuntu 26.04，用来测试这个项目。

但它本质还是一个"子系统"，资源还是共用你 Windows 电脑的。你电脑 16GB 内存、剩 100GB 磁盘，跑小样本测试可以，跑正式全量任务会很吃力。

🧩 第一步：安装 WSL2 和 Ubuntu 26.04

WSL2 可以理解成 Windows 自带的一个"轻量 Linux 虚拟机"，比 VirtualBox 轻便很多。

1. 以管理员身份打开 PowerShell

在 Windows 搜索框输入 PowerShell，右键点击"Windows PowerShell"，选择"以管理员身份运行"。

2. 安装 WSL2 和 Ubuntu 26.04

在 PowerShell 里输入以下命令，然后回车：

powershell

复制代码

wsl --install -d Ubuntu-26.04

这个命令会自动下载并安装 WSL2 和 Ubuntu 26.04。

如果提示找不到 Ubuntu-26.04 ，说明 WSL 的在线列表还没更新，需要手动下载 .wsl 镜像文件：

打开浏览器，访问：https://releases.ubuntu.com/26.04/ubuntu-26.04-wsl-amd64.wsl，下载这个文件（大约 400MB）。

在 PowerShell 里执行：

powershell
复制代码
wsl --install --from-file "你下载的路径\ubuntu-26.04-wsl-amd64.wsl"

3. 设置 Ubuntu 用户名和密码

安装完成后，会提示你创建一个 Linux 用户名和密码。这个密码就是 Ubuntu 的 sudo 密码，后面安装系统时会用到，一定要记住。

⚙️ 第二步：启用 systemd 并配置资源

1. 启用 systemd（让 Linux 的"后台服务大管家"上班）

为什么需要这一步？ 这个项目的安装脚本需要用 systemctl 来把服务注册成后台服务。WSL2 默认可能没开启 systemd，不开启安装会失败。

打开 Ubuntu 终端（在 Windows 搜索框输入 Ubuntu 26.04 打开），执行：

bash

复制代码

sudo nano /etc/wsl.conf

在打开的编辑器中，输入以下内容：

ini

复制代码

[boot]
systemd=true

按 Ctrl + X，然后按 Y，再按回车保存。

2. 配置 WSL2 的内存和 CPU

为什么需要这一步？ WSL2 默认会占用 Windows 一半的内存，可能让你的电脑变卡。我们需要限制一下。

在 Windows 里，打开文件资源管理器，进入 C:\Users\你的用户名\ 目录。新建一个文本文档，命名为 .wslconfig（注意前面有个点，没有 .txt 后缀）。

用记事本打开它，输入：

ini

复制代码

[wsl2]
memory=8GB
processors=4
swap=8GB

保存后，在 PowerShell 里执行 wsl --shutdown 重启 WSL2。

📦 第三步：把离线发布包和数据传进 Ubuntu

外行解释：就像往新电脑里拷贝文件一样。WSL2 有个很方便的功能，可以直接访问你 Windows 的磁盘。

1. 在 Windows 里准备好文件夹

把你的完整离线发布包（.tar.gz 文件）和业务数据放到一个文件夹里，比如：

text

复制代码

D:\qijiang_deploy\

2. 在 Ubuntu 里访问 Windows 文件

打开 Ubuntu 终端，你的 Windows D 盘在 Ubuntu 里的路径是 /mnt/d/。

先确认一下能看到文件：

bash

复制代码

ls /mnt/d/yancao

如果能看到 你的文件，说明成功了。

🚀 第四步：部署系统

1. 解压并校验

在 Ubuntu 终端里依次执行：

bash

复制代码

# 创建安装目录
sudo mkdir -p /opt/qijiangTobaccoSystem

# 解压发布包（把 /mnt/d/yancao/ 换成你的实际路径）
sudo tar -xzf /mnt/d/qijiang_deploy/qijiangTobaccoSystem-ubuntu-amd64.tar.gz -C /opt/qijiangTobaccoSystem

下一步的进入安装目录可能会失败：

因为用 sudo mkdir 和 sudo tar 解压，生成的文件和目录都属于 root ，普通用户 user 没有"进入"这个目录的权限。

把目录所有权改成你自己

执行：sudo chown -R $USER:$ USER /opt/qijiangTobaccoSystem

这条命令的意思是：把 /opt/qijiangTobaccoSystem 以及里面所有文件，都改成你当前用户 user 所有。

然后你就能正常进入了：

复制代码

# 进入安装目录
cd /opt/qijiangTobaccoSystem

# 校验文件完整性
sha256sum -c SHA256SUMS

问题解答：

1. /opt/qijiangTobaccoSystem 创建在哪？存储在哪？

位置：它创建在 Linux 系统的根目录 / 下。

存储在哪 ：它存储在 Linux 自己的虚拟硬盘里 （比如 VirtualBox 的 .vdi 文件，或者 WSL 的 ext4.vhdx 文件）。

/opt 是什么意思 ：opt 是 Optional（可选）的缩写。在 Linux 世界里，这是专门用来安装第三方商业软件 或大型独立应用 的标准目录（类似于 Windows 里的 C:\Program Files）。

2. 为什么不能直接在 D:\yancao（即 /mnt/d/ 或 /media/sf_yanco）里解压运行？

这里涉及跨系统文件系统的巨大差异，主要有三大原因：

① 文件系统不同（NTFS vs ext4）

Windows 的 D 盘是 NTFS 格式。

Ubuntu 自己的硬盘是 ext4 格式。

当你在 Ubuntu 里访问 D:\yancao（挂载为 /mnt/d/ 或 /media/sf_yanco），Linux 需要通过特殊的驱动（如 vboxsf 或 drvfs）把 Windows 的权限转换成 Linux 权限。这就导致你之前遇到的"文件夹为空"、"必须是超级用户才能卸载"等坑。把 Linux 软件放在 NTFS 盘里运行，极易因为权限问题或文件锁机制导致程序崩溃。

② 性能极差

跨系统挂载的文件读写速度非常慢（因为需要经过虚拟化层或子系统转换）。如果这是个数据库系统（TobaccoSystem 听起来像业务系统），高并发读写在共享文件夹里会卡得让你怀疑人生。

③ 安全性

/mnt/d/（你的 D 盘）随时可能被 Windows 宿主机关机、拔除、或者你自己在 Windows 下不小心删了。把系统部署在 /opt，意味着它被安全地放在了 Linux 自己的地盘里，独立且稳定。
问题解答：

为什么校验？ 确认文件在传输过程中没有损坏。所有文件都显示 OK 才能继续。如果出现 FAILED，说明包损坏了，需要重新拷贝。

2. 执行安装脚本

bash

复制代码

sudo ./install.sh --skip-data-import

为什么先跳过数据导入？ 先验证服务、数据库、页面能不能正常启动。基础环境没问题了，再导入大数据。

安装过程中可能会提示你设置几个密码，这几个密码一定不要搞混：

密码	用途
Ubuntu sudo 密码	你刚才创建的 Ubuntu 用户密码（12345）
MySQL root 密码	数据库管理员密码，自己定一个记住（12345）
tobacco_app 数据库密码	也是自己定（12345）
网页 root 密码	登录系统用的密码，至少 12 位，这个最重要（ZDN1234567890）

如果刚刚安装失败

把整个目录改成了你个人用户所有，但安装脚本后面会创建一个专门的 mysql 用户，并用它来运行 MySQL。如果目录权限太严，mysql 用户就进不去，也无法执行 mysqld。

先检查一下

执行这两条命令看看：

bash
复制代码
ls -ld /opt/qijiangTobaccoSystem
ls -l /opt/qijiangTobaccoSystem/runtime/mysql/mysql-8.4.10-linux-glibc2.28-x86_64-minimal/bin/mysqld
如果第一行显示类似 drwx------，说明只有你自己能进，mysql 用户进不去。

如果第二行没有 x（执行权限），mysqld 就跑不起来。

解决办法：放宽权限，让所有用户能读能执行

执行：

bash
复制代码
sudo chmod 755 /opt/qijiangTobaccoSystem
sudo chmod -R a+rX /opt/qijiangTobaccoSystem
解释一下：

chmod 755：让目录所有者可读写执行，其他人可读可执行。

chmod -R a+rX：递归地让所有用户可读，目录和已有可执行文件可执行。X 是大写，表示"如果是目录，或者已经有执行权限，就加执行权限"。

然后重新运行安装：

bash
复制代码
cd /opt/qijiangTobaccoSystem
sudo ./install.sh --skip-data-import

3. 启动服务并检查

bash

复制代码

./start.sh
./status.sh
curl http://127.0.0.1:8002/health

如果看到类似 {"status":"ok","service":"tobacco-risk-backend","rawDb":"ok","anomalyDb":"ok"}，说明基础部署成功了。

这三条命令是在 Ubuntu 的终端 里输入的，也就是你刚才输入 sudo ./install.sh --skip-data-import 的那个黑色窗口。不是 Windows 的 PowerShell，也不是 CMD。

它们的作用是：

text
复制代码
./start.sh       启动系统服务（MySQL + 网页后端）
./status.sh      查看服务有没有启动成功
curl .../health  给系统做一次“体检”，看数据库和网页后端是否正常
你可以把 ./start.sh 理解成 按开机键 ，./status.sh 是 看指示灯 ，curl .../health 是 让系统自己报一句"我很好"。
如果执行./start.sh失败：

下面这种情况
复制代码
user@DESKTOP-LS1H1O0:/opt/qijiangTobaccoSystem$ ./start.sh
awk: fatal: cannot open file `/opt/qijiangTobaccoSystem/web/tobacco_system/.env.local' for reading: Permission denied
start.sh 想读取 .env.local 这个配置文件，但当前用户没有权限读它。

.env.local 里面存的是数据库连接密码等配置，安装脚本生成它时可能设了比较严的权限，只有 root 或 qijiang 用户能读。你现在用普通用户 user 跑 ./start.sh，就被挡住了。

先确认文件在不在

执行：

bash
复制代码
ls -l /opt/qijiangTobaccoSystem/web/tobacco_system/.env.local
如果显示文件存在，只是权限问题，看下面"改权限"。

如果提示 No such file or directory，说明安装没完全成功，需要先重新安装。

解决办法：给 .env.local 加上读权限

执行：

bash
复制代码
sudo chmod 644 /opt/qijiangTobaccoSystem/web/tobacco_system/.env.local
644 的意思是：所有者可读写，其他人可读。这样你当前用户就能读了。

如果还有问题

如果上面的问题解决完了执行./start.sh

还是不能正常启动如下：
复制代码
user@DESKTOP-LS1H1O0:~$ cd /opt/qijiangTobaccoSystem
./start.sh


ERROR: Web service did not become healthy within 60 seconds.


● qijiang-tobacco.service - Qijiang Tobacco Risk Web Service
     Loaded: loaded (/etc/systemd/system/qijiang-tobacco.service; enabled; preset: enabled)
     Active: activating (auto-restart) (Result: exit-code) since Sat 2026-09-19 16:05:37 CST; 662ms ago
 Invocation: 6a164142348d4eb7a1a41ca23b8ebeb1
    Process: 2349 ExecStartPre=/opt/qijiangTobaccoSystem/wait_for_db.sh /opt/qijiangTobaccoSystem/.venv/bin/python (code=exited, status=0/SUCCESS)
    Process: 2352 ExecStart=/opt/qijiangTobaccoSystem/.venv/bin/python -m uvicorn backend.app.main:app --host 0.0.0.0 --port 8002 (code=exited, status=3)
   Main PID: 2352 (code=exited, status=3)
   Mem peak: 107.4M
        CPU: 1.496s
服务反复重启确实让人着急，但别担心，这是部署中常见的问题。uvicorn 进程以状态码 3 退出，通常意味着应用在启动过程中遇到了错误，比如代码导入失败、缺少环境变量或依赖包等。我们需要找到具体的报错信息，才能对症下药。

🔍 第一步：查看服务的详细错误日志

systemd 服务反复重启，说明日志可能很多。我们可以用下面的命令，让 journalctl 只输出最近的日志，并持续滚动显示，方便你看到最新的错误信息。

请在 Ubuntu 终端中执行：

bash
复制代码
sudo journalctl -u qijiang-tobacco.service -n 50 -f --no-pager
如果日志里写得很清楚有：

text
复制代码
PermissionError: [Errno 13] Permission denied: '/opt/qijiangTobaccoSystem/indicators/versions'
意思是：Web 服务启动时，想在 indicators/versions 目录下创建子目录，但它没有写权限。

这是因为之前我们把整个 /opt/qijiangTobaccoSystem 的所有者改成了你的用户 user，而实际运行 Web 服务的用户是 qijiang（安装脚本创建的专用用户），所以 qijiang 无法在 indicators 里写文件。

解决办法：把安装目录的所有权改回 qijiang

先停掉反复重启的服务：

bash
复制代码
sudo systemctl stop qijiang-tobacco.service
然后把整个项目目录的所有者改成 qijiang：

bash
复制代码
sudo chown -R qijiang:qijiang /opt/qijiangTobaccoSystem
再给目录合适的权限，确保 qijiang 能读写执行：

bash
复制代码
sudo chmod -R u+rwX,g+rwX,o+rX /opt/qijiangTobaccoSystem

📊 第五步：导入业务数据

你有完整的数据，现在需要把数据导入系统。有两种方式：

方式一：通过网页上传（推荐，适合日常使用）

在 Windows 浏览器打开 http://127.0.0.1:8002
用 root 和安装时设置的网页 root 密码登录
新建批次，然后依次上传五类数据文件

五类数据是：

C 端扫码销售流水（CSV）
订单主表（XLSX）
客户信息（XLSX）
客户 GIS（XLSX）
订单明细（XLSX，可多个）

我们在上传C 端扫码销售流水（CSV）时可能会显示'utf-8' codec can't decode byte 0xb2 in position 95: invalid start byt

因为这个 mergedData.csv 不是 UTF-8 编码，系统读的时候按 UTF-8 解码，遇到一个不认识的字节，就失败了。

Windows 上很多 CSV 默认是 GBK / GB2312 / ANSI 编码，尤其是 Excel 另存为 CSV 的时候。这个系统要求 UTF-8，所以需要先把 CSV 转成 UTF-8，再上传。

最简单的方法：在 WSL 里用 iconv 转码

打开你的 Ubuntu 终端，按下面做。

1. 进入小样本文件夹

假设你的小样本在：

text
复制代码
D:\qijiang_small_sample
在 Ubuntu 里对应路径是：

text
复制代码
/mnt/d/qijiang_small_sample
执行：

bash
复制代码
cd /mnt/d/yancao/綦江小样本
ls -l
确认能看到 mergedData.csv。

2. 转成 UTF-8

执行：

bash
复制代码
iconv -f GBK -t UTF-8 mergedData.csv -o mergedData_utf8.csv
解释：

-f GBK：原文件按 GBK 读；

-t UTF-8：输出成 UTF-8；

-o mergedData_utf8.csv：新文件名。

如果这条报错，比如提示 illegal input sequence，就改用：

bash
复制代码
iconv -f GB18030 -t UTF-8 mergedData.csv -o mergedData_utf8.csv
GB18030 是 GBK 的超集，兼容性更好。

如果上传之后无法得到结果

现在必须做三件事：

第一步：去看具体报错日志（最关键）

"算法执行失败"是个大帽子，具体原因藏在日志里。请在 Ubuntu 终端执行：

bash
复制代码
cd /opt/qijiangTobaccoSystem
ls -lt logs/webTasks | head
这会列出最新几个任务日志文件。找到最近的一个（比如 task_xxx.log），然后查看最后 50 行：

bash
复制代码
tail -n 50 logs/webTasks/刚才看到的文件名.log
如果日志里没看明白，可以再看看算法日志：

bash
复制代码
ls -lt logs/algorithm/production | head
tail -n 50 logs/algorithm/production/最新文件名.log
请把看到的具体报错信息（比如 MemoryError、KeyError、ValueError 等）复制发我。

方式二：使用 `--force-data-import` 导入随包数据

如果你的数据是随发布包一起打包的，可以用：

bash

复制代码

sudo ./install.sh --force-data-import

注意：这种方式会把数据导入到兼容旧数据的 legacy-current 批次（页面显示为"历史数据集"），不是日常新建批次的导入方式。

用真实数据跑正式任务

数据导入完成后：

在网页里提交"正式识别"任务
选择全量或月份区间
等待任务完成（可能会停在 25% 很久，这是正常的，表示算法正在读取数据、建立缓存、计算评分，不是卡死了）
任务完成后，选择新的正式结果版本，查看风险总览、B 端和 C 端结果

重要提醒 ：你的电脑 16GB 内存、剩余 100GB 磁盘，跑小样本快速验证没问题，但跑全量任务会非常吃力，甚至可能跑不动。如果全量数据很大，建议先在 WSL2 里跑小样本验证流程，全量任务申请服务器来跑。

🌐 第六步：让局域网访问（可选）

如果你想让课题组的其他电脑也能访问你 WSL2 里的系统，需要做端口转发。

1. 获取 WSL2 的 IP 地址

在 Ubuntu 终端里执行：

bash

复制代码

ip addr show eth0 | grep 'inet '

记下类似 172.30.144.91 的 IP 地址。

2. 在 Windows 上配置端口转发

以管理员身份打开 PowerShell，执行：

powershell

复制代码

netsh interface portproxy add v4tov4 listenport=8002 connectport=8002 connectaddress=172.30.144.91

然后，在 Windows 防火墙里放行 8002 端口。

3. 局域网访问

其他电脑浏览器访问：

text

复制代码

http://你的Windows电脑IP:8002

注意：WSL2 的 IP 地址在重启后可能会变化，如果转发失效了，重新获取 IP 再执行一遍转发命令即可。

WSL2 的一个小提醒

WSL2 不是一直开着的。

你 Windows 重启后，Ubuntu 里的服务会停。需要重新打开 Ubuntu 终端，执行：

bash

复制代码

cd /opt/qijiangTobaccoSystem
./start.sh

然后浏览器再访问 http://127.0.0.1:8002。

綦江烟草部署（在wsl2里部署）

WSL2 是什么？

🧩 第一步：安装 WSL2 和 Ubuntu 26.04

1. 以管理员身份打开 PowerShell

2. 安装 WSL2 和 Ubuntu 26.04

3. 设置 Ubuntu 用户名和密码

⚙️ 第二步：启用 systemd 并配置资源

1. 启用 systemd（让 Linux 的"后台服务大管家"上班）

2. 配置 WSL2 的内存和 CPU

📦 第三步：把离线发布包和数据传进 Ubuntu

1. 在 Windows 里准备好文件夹

2. 在 Ubuntu 里访问 Windows 文件

🚀 第四步：部署系统

1. 解压并校验

1. /opt/qijiangTobaccoSystem 创建在哪？存储在哪？

2. 为什么不能直接在 D:\yancao（即 /mnt/d/ 或 /media/sf_yanco）里解压运行？

2. 执行安装脚本

先检查一下

解决办法：放宽权限，让所有用户能读能执行

3. 启动服务并检查

先确认文件在不在

解决办法：给 .env.local 加上读权限

如果还有问题

🔍 第一步：查看服务的详细错误日志

解决办法：把安装目录的所有权改回 qijiang

📊 第五步：导入业务数据

方式一：通过网页上传（推荐，适合日常使用）

我们在上传C 端扫码销售流水（CSV）时可能会显示'utf-8' codec can't decode byte 0xb2 in position 95: invalid start byt

最简单的方法：在 WSL 里用 iconv 转码

1. 进入小样本文件夹

2. 转成 UTF-8

如果上传之后无法得到结果

现在必须做三件事：

第一步：去看具体报错日志（最关键）

方式二：使用 --force-data-import 导入随包数据

用真实数据跑正式任务

🌐 第六步：让局域网访问（可选）

1. 获取 WSL2 的 IP 地址

2. 在 Windows 上配置端口转发

3. 局域网访问

WSL2 的一个小提醒

1. `/opt/qijiangTobaccoSystem` 创建在哪？存储在哪？

2. 为什么不能直接在 `D:\yancao`（即 `/mnt/d/` 或 `/media/sf_yanco`）里解压运行？

解决办法：给 `.env.local` 加上读权限

解决办法：把安装目录的所有权改回 `qijiang`

最简单的方法：在 WSL 里用 `iconv` 转码

方式二：使用 `--force-data-import` 导入随包数据