运行环境
一台 Windows 电脑、内网服务器或云服务器。建议 2 核 CPU、4GB 内存、20GB 可用磁盘；使用强化安装包时不需要单独安装 Python 或 SQLite。
一、部署前物料准备
网络与端口
服务器需要能访问邮箱 IMAP/SMTP、HiFleet API 和所选 LLM 接口。对外访问时开放系统端口，例如 8081 端口。
邮箱资料
准备邮箱账号、第三方应用密码、IMAP 地址/端口、SSL 设置，以及需要读取的文件夹列表。
第三方应用密码不是网页登录密码。请在邮箱网页版或企业邮箱后台开启 IMAP/SMTP 后，到“账户与安全”“客户端设置”或“授权码/App Password”页面生成。阿里企业邮箱通常叫“三方客户端安全密码”，QQ/163 等国内邮箱常叫“授权码”，Gmail/Outlook 常叫“App Password”。
HiFleet API Key
用于公开船货盘、港口、预抵船、获取联系方式和船货盘富化等能力。没有 Key 时可在系统设置页按“发送验证码 → 注册/登录 → 获取 Key → 保存设置”的流程申请。
LLM 接口
准备 OpenAI 兼容接口地址、API Key、模型名、超时时间和 token 限制。邮件会先脱敏后再送入 LLM 解析。
访问策略
个人使用可绑定本机 127.0.0.1；多人访问建议配置账号登录、HTTPS、服务器防火墙和访问白名单。
终端与浏览器
建议使用 Chrome 或 Edge。手机端和窄屏可使用紧凑布局，船盘、货盘等宽表格支持左右拖动查看完整内容。
用户与权限
首次启动会自动创建管理员账号；管理员可创建普通用户、重置密码、停用或删除普通用户。登录日志可记录时间、用户、成功/失败、IP、国家/城市和浏览器信息。
阿里云 ECS 云服务器租用推荐
适合团队共享、长期运行或需要公网访问的私有部署，推荐按包年包月购买。
- 实例
- 经济型 e ecs.e-c1m2.large，2 vCPU，4 GiB
- 镜像
- Ubuntu 26.04 64 位
- 系统盘
- ESSD Entry，100 GiB，随实例释放，未开启性能突发
- 地域
- 选择离自己所在城市较近的地域
- 带宽
- 专有网络，按使用流量，5 Mbps
- 计费方式
- 包年包月
如果客户对邮件内容非常敏感，可以把系统部署在客户内网，并选择客户自己的私有 LLM 或企业托管 LLM。HiFleet 不接收邮箱密码；私密船货盘富化可在设置页关闭。完整 HiFleet API Key 仅在创建或发放时显示一次，后续页面只显示脱敏前缀和末 4 位。
二、标准部署步骤
选择部署方式个人试用可部署在本地电脑；团队使用建议部署在客户云服务器或公司内网服务器。
安装运行环境确认服务器能访问 IMAP、SMTP、HiFleet API 和 LLM 接口；强化安装包会自带运行所需组件。
上传系统文件上传强化安装包、模板文件和示例配置。不要用本地测试配置覆盖客户服务器的
config.json 配置文件。申请或配置 HiFleet API Key没有 Key 时，在设置页用邮箱或手机号接收验证码；如需要人机校验，按接口返回的人机页面完成后重试发码。注册或登录成功后立即保存完整 Key。
填写系统设置管理员在前端设置页录入邮箱、文件夹、HiFleet API Key、LLM、同步间隔、私密富化开关和邮件预览地址；展示天数在左侧筛选条件中由用户自行调整。
启动服务指定监听地址和端口后启动，例如监听
0.0.0.0:8081 供局域网或公网访问。配置首次登录和用户首次启动后用 data/initial_admin_password.txt 中的初始管理员登录，修改管理员密码，再为团队成员创建普通用户。
执行首次同步点击“同步邮箱”，检查运行信息、异常邮件、船盘/货盘条目、HiFleet 富化状态和订阅页用量明细。
配置安全与运维按客户要求增加 HTTPS、账号登录、备份策略、日志保留策略和服务器安全组。
三、关键参数设置
| 参数 | 用途 | 建议 |
|---|---|---|
email / email_accounts | 主邮箱和附加邮箱账号。 | 每个账号使用独立第三方密码；新增账号密码留空时不会覆盖旧密码。 |
imap_host / imap_port / imap_ssl | IMAP 收信服务器。 | 企业邮箱一般使用 993 + SSL；先用端口测试确认可连通。 |
mailboxes | 读取的邮箱文件夹。 | 一行一个，例如 INBOX、垃圾邮件 或客户自定义文件夹。 |
mail_parse_interval_minutes | 自动同步邮箱间隔。 | 常用值 10 分钟；邮箱量大时可适当调大。 |
| 前端展示天数 | 左侧筛选条件中的个人浏览偏好，不再属于系统设置。 | 默认 5 天；普通用户可自行调整；影响私密/公开船货盘、匹配和搜索推荐。 |
auth.enabled / auth.admin_password | 登录鉴权、管理员初始密码和会话有效期。 | 建议启用鉴权；首次登录后立即修改管理员密码，不要多人共用管理员账号。 |
hifleet_api_key | HiFleet 港口、预抵船、公开船货盘、获取联系方式和富化接口。 | 建议客户使用独立 key，便于用量跟踪和权限管理。 |
| 订阅与用量 | 在订阅页查看本周用量、余额、调用明细、订阅记录和 HiFleet Skills 控制台。 | 余额以 availablePoints 为准；订阅、付款和发票信息以 HiFleet 控制台真实返回为准。 |
llm_api_base / llm_api_key / llm_model | LLM 解析邮件内容。 | 支持 OpenAI 兼容接口；涉密客户可选择私有化或企业版 LLM。 |
llm_external_email_parsing_approved | 是否允许把脱敏邮件发送给 LLM。 | 必须由客户明确授权；未授权时不应调用外部 LLM 解析邮件。 |
mail_preview_base_url | 邮件预览链接基础地址。 | 公网部署填写公网地址；内网部署填写局域网地址或域名。 |
smtp_host / smtp_port / smtp_security | 系统内回复邮件。 | 可先留空，系统会按 IMAP 地址推断；正式使用前建议测试。 |
四、客户关心的数据安全
- 本地保存：邮箱账号、第三方密码、原始邮件、SQLite 数据库、已关注和跟进状态保存在客户部署环境中，由客户自行管理备份和访问权限。
- 邮箱密码：仅用于连接客户配置的 IMAP/SMTP 服务，不会发送给 HiFleet 或 LLM。
- LLM 解析：只有开启“允许发送脱敏邮件给 LLM”后，系统才会把脱敏后的邮件主题和正文发送到配置的 LLM；邮箱、电话、微信、WhatsApp 等联系方式会先脱敏，船名、港口、货种、DWT、Laycan 等业务字段会保留用于解析。
- 私密船货盘 HiFleet 富化：仅在设置页开启后调用；发送的是富化所需的脱敏业务字段，例如船名、IMO、MMSI、港口、DWT、Laycan、船型、货种和业务说明，不发送邮箱密码和已识别的联系方式字段。
- 关闭私密富化后：邮箱船盘/货盘仍可本地展示、搜索和匹配，但不再补充 HiFleet 港口 ID、船舶档案和服务端 Tags；公开船货盘、预抵船、订阅与用量查询仍可使用 HiFleet。
- 公开船货盘和预抵船：查询时发送港口、筛选条件、公开记录 ID 或预抵船记录 ID；获取联系方式时按记录 ID 调用，只有 HiFleet 返回明文联系方式时才展示。
- 计费与失败：建议按业务结果计费，私密邮件富化按邮件条数、联系方式按成功获取且不重复计费、预抵港查询按查询次数；超时、网络错误、5xx、无明文联系方式或余额不足不应扣费。
- 用户与审计：普通用户登录后才能访问系统；管理员可管理普通用户，并在登录日志中查看登录时间、IP、来源国家和城市。
- 访问控制：多人或公网部署时应启用登录鉴权、HTTPS、服务器防火墙、访问白名单、操作日志和权限分级。
- Key 安全：完整 HiFleet API Key 仅在创建、发放或轮换时显示一次；设置页和用量页只显示脱敏前缀和末 4 位。
风险边界：选择外部 LLM 或开启私密船货盘 HiFleet 富化后，相关脱敏业务字段会离开客户服务器。私有部署的意义是让客户自己决定是否打开这些能力，并控制服务器、网络和账号权限。