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

账户与邮件流程

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

邮件服务不可用时，邮箱验证码、密码重置和邀请注册无法完成。请确认 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 密钥，也不会发送邮件。

README.md Unescape Escape

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

主要功能

运行要求

配置环境变量