pipeline-lifetime/README.md

供水管道健康状态与剩余寿命评估系统

用于上传管道数据，完成健康状态和剩余寿命预测，并导出结果表格。系统包含用户认证、邮箱二次认证、管理员用户管理、邀请注册和上传记录下载等功能。

主要功能

• 上传 Excel 数据并执行预测，生成结果文件和图像。
• 用户使用用户名或邮箱登录，陌生设备需完成邮箱二次认证。
• 支持公开自助注册，也支持管理员在关闭公开注册后发送注册链接。
• 支持一次性密码重置链接、修改登录邮箱、受信设备管理和会话撤销。
• 管理员可搜索用户、启停账号、发送密码重置链接、撤销受信设备，以及下载上传记录。
• 上传记录和用户列表均支持分页。

运行要求

• Docker 和 Docker Compose，推荐用于部署。
• 本机开发建议使用 Python 3.12 和 Conda。
• 邮件认证、密码重置和邀请注册需要配置 Resend。

配置环境变量

复制模板创建实际配置文件：

cp .env.example .env

.env 用于实际运行配置，不应提交到版本库。.env.local 用于本机开发覆盖，空值表示继续使用 .env 中的值。优先级为：系统环境变量、.env.local、.env。

生产环境至少应配置：

APP_ENV=production
DEBUG=false
SECRET_KEY=请填写高强度随机密钥
ADMIN_USERNAME=admin
ADMIN_PASSWORD=请填写管理员初始密码
ADMIN_EMAIL=管理员邮箱
DATABASE_URL=sqlite:////app/data/pipe_survival.db
RESEND_API_KEY=Resend_API_密钥
RESEND_FROM_EMAIL=已验证的发件人地址
SESSION_COOKIE_SECURE=true

可使用下列命令生成 SECRET_KEY：

python -c "import secrets; print(secrets.token_hex(32))"

其余变量和默认值见 .env.example。其中，EMAIL_CODE_MINUTES 控制邮箱验证码有效期，PASSWORD_RESET_TOKEN_MINUTES 控制密码重置和邀请注册链接的有效期。

Docker 部署

直接构建

docker compose up -d --build
docker compose logs -f

服务默认监听 5005 端口。数据通过以下目录持久化：

本机目录	容器目录	用途
./data	/app/data	SQLite 数据库和运行日志
./data/uploads	/app/uploads	已上传的原始文件与预测结果
./data/images	/app/static/images	预测图像

不要在更新时使用 docker compose down -v，否则可能删除持久化卷。数据库结构会在启动时自动补齐，不会删除现有数据。

导入已导出的镜像

将镜像包、docker-compose.yml 和 .env 放到同一目录后执行：

sudo docker load -i pipeline-lifetime_YYYYMMDD.N.tar
docker compose up -d
docker compose logs -f

更新镜像时先停止旧容器即可，保留 data 目录：

docker compose down
sudo docker load -i pipeline-lifetime_YYYYMMDD.N.tar
docker compose up -d

本机开发

安装 Python 依赖后，使用 .env.local 覆盖开发配置：

conda create -n pipeline-lifetime python=3.12 -y
conda activate pipeline-lifetime
pip install -r requirements.txt
npm install
npm run build:css
python main.py

访问 http://127.0.0.1:5005。本机 HTTP 开发时请将 SESSION_COOKIE_SECURE=false。修改模板中的 Tailwind 类后，需要执行 npm run build:css；持续开发可使用：

npm run watch:css

也可使用 Docker 开发覆盖配置：

docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

账户与邮件流程

1. 登录先校验用户名或邮箱、密码和图形验证码。
2. 未受信设备会收到 6 位邮箱验证码。验证码默认 10 分钟有效，重发间隔默认 60 秒。
3. 勾选“信任此设备”后，30 天内无需邮箱二次认证。勾选“保持登录状态”后，登录状态最长保持 7 天。
4. 找回密码会发送一次性重置链接。链接使用后失效，重置成功会撤销其他会话和受信设备。
5. 管理员可发送注册链接。受邀用户可在公开注册关闭时完成注册，注册链接同样为一次性链接。

邮件服务不可用时，邮箱验证码、密码重置和邀请注册无法完成。请确认 Resend 的 API 密钥、发件人域名和 DNS 验证状态正确。

反向代理建议

公开部署建议由 Nginx 提供 HTTPS，并将请求头转发给应用：

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

应用会基于当前请求生成密码重置和注册链接。请确保用户访问的公网域名能够正确转发到该服务。

NPMplus 上传文件返回 500

如果小请求可以正常转发，但上传稍大的文件时 Nginx 返回 HTML 格式的 500，先检查 NPMplus 的错误日志：

sudo docker exec npmplus sh -lc \
  "grep -E 'client_body_temp.*Permission denied' /data/nginx/logs/error.log | tail"

Nginx 会在请求体超过内存缓冲区后将内容写入 client_body_temp。当 NPMplus 以非 root 的 PUID、PGID 运行，而 /usr/local/nginx/*_temp 目录被 root 拥有且权限为 0700 时，写入会因权限不足失败并返回 500。可按实际的 PUID、PGID 修复全部临时目录；下面以 1000:1000 为例：

sudo docker exec -u 0 npmplus sh -lc '
  for name in client_body_temp proxy_temp fastcgi_temp scgi_temp uwsgi_temp; do
    chown -R 1000:1000 "/usr/local/nginx/$name"
    chmod 700 "/usr/local/nginx/$name"
  done
'
sudo docker exec -u 1000:1000 npmplus nginx -t

不要在 NPMplus 的 Compose 服务中直接设置 user: 1000:1000，其启动脚本需要先以 root 初始化，再根据 PUID、PGID 降权运行。检查 Nginx 配置时也应指定相同的运行账号：

sudo docker exec -u 1000:1000 npmplus nginx -t
sudo docker exec -u 1000:1000 npmplus nginx -T

以 root 身份执行 nginx -t 或 nginx -T 可能重新改变临时目录属主，使上传故障复发。此问题与 HTTPS、CrowdSec 拦截和 client_max_body_size 无关；如果响应为 413 或 403，应分别检查请求体大小限制和访问控制日志。

测试

python -m pytest -q

测试不使用真实 Resend 密钥，也不会发送邮件。