部署指南

面向部署者与运维人员。
项目说明
文档名称TrueAGT 部署指南
适用对象部署者与运维人员
配套文档《产品介绍》《用户手册》《API 参考》《多节点协作配置指南》《数据流向声明》

1. 部署前的责任确认

TrueAGT 是工具,不是服务。 当你部署 TrueAGT 并向他人(尤其是社会公众)提供服务时,你就是法律意义上的「生成式人工智能服务提供者」,需自行履行相应义务。

部署完成后,以下事项需要由你(部署者/运营方)完成,TrueAGT 只提供相应的能力而不替代你的责任:

义务落地方式
内容安全审核启用内容安全过滤机制,并自备、维护词表;需要时叠加模型护栏与人工复核
违法内容的处置与报告审计链与处置留痕记录每一条发现与处置;报告环节由人工完成并留证
生成合成内容标识配置服务提供者名称与编码,保证显式标识与隐式编号可追溯到真实主体
投诉举报机制页面内置举报入口,管理员需配置处理流程并对外公示联系方式与处理时限
算法备案与安全评估面向公众提供服务时按主管机关要求办理
日志与留存运行日志与审计记录的留存期限(相关办法要求不少于六个月)需由备份与日志轮转策略落实

TrueAGT 不保证部署者已合规,也不承担部署者的合规责任;同样,TrueAGT 不宣称已通过任何国家认证,也不宣称部署即等同于合规。

若不向境内公众提供服务(自用或组织内部使用),则不适用备案与安全评估义务,但个人信息保护、数据安全等一般性法律义务仍然存在。

部署完成后请复核:服务端对运行期产生的对话内容具备可发现、可处置的能力——这既是法定要求,也是正确配置的目标状态。请勿在对外宣传中声称运营方无法查看任何数据。

2. 环境要求

项目要求
操作系统Linux / Windows / macOS
运行时Python 3.10 及以上;Windows 安装包无需预装 Python
运行时依赖无第三方 Python 包,无需执行包安装命令
模型服务任一 OpenAI 兼容端点 / Anthropic / Ollama,需从部署机网络可达
磁盘预留会话数据库、附件与日志空间,建议不少于 1 GB
端口默认 8765(可在配置中调整)

3. Windows 安装包部署

面向最终用户,全程无需安装 Python 或任何依赖:

  1. 解压 trueagt-0.9.233-win-setup.zip;
  2. 双击 install.bat,安装完成后桌面与开始菜单出现「TrueAGT」快捷方式;
  3. 双击「TrueAGT」图标启动,约数秒后浏览器自动打开对话页面(默认 http://127.0.0.1:8765)。

安装位置为当前用户的 %LOCALAPPDATA%\TrueAGT,会话数据、长期记忆与日志分别位于该目录下的 data/ 与 logs/。

服务器场景、容器部署、监控告警等内容见以下章节。


4. 发布包部署

4.1 准备配置

发布包中不包含 config.json,首次部署必须从模板创建:

cd trueagt
cp config/config.example.json config.json

最小可用配置示例:

{
  "llm": {
    "provider": "openai",
    "model": "你的模型名",
    "api_key": "你的密钥",
    "base_url": "http://127.0.0.1:9000/v1",
    "retries": 2
  },
  "server": {
    "host": "127.0.0.1",
    "port": 8765,
    "auth": { "registration": "open", "session_ttl_hours": 720 },
    "rate_limit": { "max_requests": 60, "window_seconds": 60 }
  }
}

4.2 启动与验证

# Windows:发布包内的 TrueAGT.exe
TrueAGT.exe --config config.json

# Linux:AppImage 单文件
./TrueAGT-<版本>-x86_64.AppImage --config config.json

# 常用参数(两种平台通用)
--host 0.0.0.0 --port 8765     # 覆盖监听地址与端口
--demo                         # 离线演示模式,不调用真实模型

启动成功后日志输出监听地址、模型、鉴权状态、运行模式与已加载工具数量。验证:

curl http://127.0.0.1:8765/healthz
# 返回 {"ok": true, "version": "0.9.233"}

4.3 生产环境必须启用鉴权

两种方式任选其一:

  1. 用户注册制(推荐):设置 server.auth.registration。取值为 open(开放自助注册,第一个注册的账号自动成为管理员)、invite(需管理员发放的一次性邀请码,置于 server.auth.invite_codes)或 closed(仅由管理员在后台创建账号)。
  2. 静态访问令牌:在 server.auth_tokens 中以「令牌: 用户名」的键值形式逐一分配,该方式下使用者以管理员身份使用。

两者都未配置且数据库中无账号时,服务不校验身份,所有可达该端口的请求归入默认本地账号。内网部署也必须启用鉴权。

账号相关的默认策略(security 段):口令长度默认下限 8 位且须同时包含字母与数字;同一账号连续登录失败 5 次或同一来源地址失败 20 次即锁定 15 分钟。

4.4 Linux 部署要点

以专用账号运行,不要使用 root:

sudo useradd -r -m -s /usr/sbin/nologin trueagt
sudo mkdir -p /opt/trueagt
sudo chown -R trueagt:trueagt /opt/trueagt
sudo -u trueagt cp config/config.example.json /opt/trueagt/config.json

系统服务样例(deploy/trueagt.service)必须修改后方可用于生产。 样例中的启动命令为:

ExecStart=/usr/bin/python3 /opt/trueagt/web.py --demo --host 127.0.0.1 --port 8765

生产环境应去掉 --demo(离线演示模式不调用真实模型,仅用于演示),并按实际路径调整:

ExecStart=/usr/bin/python3 /opt/trueagt/web.py --config /opt/trueagt/config.json --host 127.0.0.1 --port 8765

启用服务:

sudo cp deploy/trueagt.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now trueagt

systemctl status trueagt        # 查看状态
journalctl -u trueagt -f        # 跟踪日志

其他注意事项:

4.5 部署形态选型

形态建议
发布包部署服务器场景首选,无需构建环节、可控性最高
容器部署环境一致性要求高或需要快速扩缩时的推荐方案
系统服务守护与上述任一形态搭配使用
Windows 安装包面向最终用户的桌面场景

5. 容器部署

发布包内提供 Dockerfile 与 docker-compose.yml。启动前必须先在本机构建 config.json,否则容器编排会把该路径当作目录创建,导致启动失败。

cp config/config.example.json config.json   # 编辑 llm 段后保存
docker compose up -d
docker compose ps
docker compose logs -f trueagt

要点:

config.json 含模型密钥,请勿提交至版本库。


6. HTTPS

6.1 使用服务端内置 TLS

同时配置 server.cert_file 与 server.key_file(PEM 格式),服务启动时即启用 HTTPS:

"server": {
  "cert_file": "certs/server.crt",
  "key_file": "certs/server.key"
}

两项缺一时将会警告并回退为明文 HTTP;证书加载失败时同样回退,请在启动日志中确认监听协议为 https。内网环境可使用自签证书,公网环境建议使用受信任证书或经由反向代理终结。

6.2 经反向代理终结(推荐)

对话采用 SSE 流式返回,反向代理必须关闭缓冲并放宽读超时:

server {
    listen 443 ssl;
    server_name trueagt.example.com;

    ssl_certificate     /etc/nginx/ssl/trueagt.crt;
    ssl_certificate_key /etc/nginx/ssl/trueagt.key;

    location / {
        proxy_pass http://127.0.0.1:8765;
        proxy_http_version 1.1;
        proxy_set_header Connection "";

        proxy_buffering off;          # SSE 必需
        proxy_read_timeout 300s;
    }
}

7. 独立后台管理端口(可选)

默认情况下后台管理页面与主对话服务共用端口。如需将管理面与业务面隔离,可启用独立管理端口:

"server": {
  "admin_enabled": true,
  "admin_host": "127.0.0.1",
  "admin_port": 8766
}

启用后,公共端口对后台管理页面与 /api/admin/* 接口一律返回 404,后台管理仅在指定地址与端口提供。建议将该端口限制在运维网络内,并通过堡垒机或 VPN 访问。


8. 多副本部署

默认单进程运行。单进程吞吐不足时,可部署多个副本共享同一份存储:

"server": { "distributed": true }

启用后将发生三处变化:

部署要点:

  1. 所有副本挂载同一个数据目录(同一主机的多个进程,或共享卷);
  2. 每个副本设置 "distributed": true 并使用不同端口;
  3. 前置负载均衡;因「停止生成」依赖请求落在同一副本,建议按来源地址保持会话粘性:
upstream trueagt {
    ip_hash;
    server 127.0.0.1:8761;
    server 127.0.0.1:8762;
}
  1. 监控需分别抓取各副本的指标端点。

限制:SQLite 写入并发能力有限,多副本适合中小规模(数十并发用户的量级)。更大规模建议将存储后端切换为 PostgreSQL(见 10.5 节)。


9. 多节点协作部署

控制面与数据面分离:中央协调器负责节点注册、令牌签发、任务中转与用量上报,不生成人工智能内容;各节点承担实际的模型调用与内容生成,业务数据留在本地节点。节点以客户端身份主动连接协调器,无需公网地址或开放入站端口。

在协调器侧:

"collab": { "enabled": true }

在节点侧:

"collab": {
  "coordinator_url": "https://coord.example.com",
  "coordinator_token": "协调器上的用户令牌",
  "node_label": "办公工作站",
  "node_execution_enabled": true
}

协作相关的配置项在服务启动时读取,修改后需重启方能生效。详细的字段说明、连通性验证与故障排查见《多节点协作配置指南》。

跨用户协作开关(allow_cross_user)默认为关闭,适用于「用户自托管中央 + 内网 + 非面向公众」的形态;开启前请完成自身合规评估,并确认该形态不会使部署者成为面向公众的服务提供者。


10. 数据、标识与备份

10.1 数据清单

数据默认位置说明
会话数据库data/trueagt.db会话、消息、事件与用量(密文落盘)
长期记忆data/users/<账号>/memory.json按账号隔离(密文落盘)
加密密钥data/trueagt.key唯一解密凭据,须单独备份,不随备份或迁移外传
运行日志logs/trueagt.log按大小轮转
审计记录data/audit_chain*.json防篡改哈希链,分段归档

10.2 静态加密

"security": {
  "encryption": {
    "enabled": true,
    "algorithm": "chacha20",
    "key_file": "data/trueagt.key"
  }
}

10.3 定期备份

"server": {
  "backup": {
    "enabled": true,
    "interval_hours": 24,
    "keep": 7
  }
}

按设定周期将数据打包到备份目录并保留最近若干份。除内置备份外,建议另行执行文件系统级备份:

sqlite3 data/trueagt.db ".backup backup/trueagt-$(date +%F).db"
tar czf backup/users-$(date +%F).tar.gz data/users
cp data/trueagt.key /secure-place/trueagt.key.bak   # 密钥与数据分开存放

恢复:停止服务 → 替换数据库文件与 data/users/(密钥文件留在原位或一并恢复)→ 启动服务 → 抽查历史会话可正常加载。

10.4 云盘存储(WebDAV)

"server": {
  "storage": {
    "type": "webdav",
    "webdav": {
      "url": "https://dav.example.com/trueagt",
      "username": "账号",
      "password": "口令",
      "sync_interval": 15
    }
  }
}

支持任何兼容 WebDAV 的网盘(如自建 Nextcloud、坚果云等)。云盘不可达时会以本地缓存继续运行并在日志中告警,恢复后自动续同步。切换存储位置也可在网页端「设置 → 数据存储」中完成,无需重启。

10.5 切换数据库后端

"database": {
  "backend": "postgresql",
  "pg_dsn": "host=127.0.0.1 port=5432 dbname=trueagt user=trueagt password=***"
}

需要先安装相应的数据库驱动;驱动缺失时会自动回退 SQLite 并记录日志,不会阻断启动。切换后端后请重启服务并完整验证。注意:已有数据不会自动迁移,需由运维自行导出导入。

10.6 生成合成内容标识

"marking": {
  "enabled": true,
  "provider": "贵方在服务协议与算法备案中使用的主体名称",
  "provider_code": "YOURCODE",
  "secret": "env:TRUE_AGT_MARKING_SECRET"
}

11. 监控与告警

11.1 Prometheus 指标

服务内置指标端点 GET /metrics。建议配置指标令牌以免指标对外暴露:

"server": { "metrics_token": "一个足够长的随机字符串" }

验证:

curl -H "Authorization: Bearer <指标令牌>" http://127.0.0.1:8765/metrics

合并发布包提供的 deploy/prometheus.yml 抓取样例与 deploy/alerts.yml 告警规则样例(覆盖服务不可达、5xx 错误率、对话连续失败、P95 耗时、限流频次)。常用指标:

指标类型含义
trueagt_http_requests_totalCounterHTTP 请求计数(按路径、状态码)
trueagt_http_duration_secondsHistogramHTTP 请求耗时分布
trueagt_chat_totalCounter对话执行总数
trueagt_chat_errors_totalCounter对话执行失败总数
trueagt_chat_cancelled_totalCounter对话被取消总数
trueagt_chat_duration_secondsHistogram对话端到端耗时分布
trueagt_tokens_totalCounterToken 消耗(按输入/输出方向)
trueagt_sessions_totalGauge会话总数
trueagt_active_usersGauge正在执行对话的用户数
trueagt_uptime_secondsGauge进程运行时长

将 Prometheus 作为数据源导入图形面板软件即可得到可视化看板。

11.2 内置巡检告警

不搭建监控栈时,可启用内置巡检:按设定间隔检查磁盘剩余空间、可用内存、错误日志增量、授权到期与登录失败次数,达到指定级别的告警推送到群机器人。服务启动、停止与异常退出同样会通知。

"security": {
  "alerts": {
    "enabled": true,
    "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx",
    "format": "wecom",
    "secret": "",
    "min_level": "warn",
    "interval_sec": 300
  }
}

11.3 日志

运行日志按大小轮转,级别可通过 server.log_level 调整。除进程日志外,以下记录为合规所需,请勿关闭并纳入备份:

请结合轮转与备份策略确保上述记录的留存期限满足适用法规要求。


12. 用户注册服务器模式(可选)

适用于「统一管理多个实例的账号」的拓扑:由一台实例担任注册服务器,其余实例将账号校验指向它。

"server": {
  "auth": {
    "mode": "remote",
    "remote_url": "https://auth.example.com:8765",
    "verify_interval_hours": 24,
    "offline_grace_hours": 168
  }
}

需要注意的是,账号数据在注册服务器上的处理由注册服务器的运营方负责;各实例的对话数据仍在实例本机,这一点不因采用该模式而改变。


13. 授权管控(可选)

对外分发时启用试用与授权码管控:

"server": {
  "license": {
    "enabled": true,
    "file": "data/license.key"
  }
}

14. 升级

14.1 发布包部署与容器部署

  1. 备份数据(含密钥文件);
  2. 停止服务;
  3. 替换代码目录(data/、logs/、config.json 保持原位);容器部署则更新镜像后重启;
  4. 启动服务,确认日志无异常;
  5. 抽查历史会话可正常加载。

发布包部署不支持应用内自动升级(相关接口会明确返回错误),请替换为新版发布包完成更新。

14.2 Windows 安装包

由你自己分发升级时,先在发布机上生成清单:

python build_pack/publish_update.py --zip dist/trueagt-0.9.233-win-setup.zip \
    --dir /var/www/trueagt/updates --notes "本次更新说明"

该命令校验压缩包、计算 SHA256 并生成 manifest.json;目录对外提供 GET /api/update/latest(版本清单)与 GET /api/update/download(安装包下载)。客户端配置:

{
  "update": {
    "url": "https://dl.example.com/api/update/latest",
    "mode": "manual",
    "check_interval_hours": 12,
    "serve_dir": "updates"
  }
}

升级流程为下载 → SHA256 校验 → 生成后台替换脚本 → 主进程退出 → 备份旧版程序 → 替换文件(config.json、data/、logs/ 原样保留)→ 按原参数重启,全过程记录于 logs/update.log。命令行亦可直接使用:

TrueAGT.exe --check-update    # 仅检查
TrueAGT.exe --upgrade         # 检查并升级

15. 常见问题

端口被占用 启动时报 Address already in use 说明端口已被其他进程占用。Linux 下用 ss -ltnp | grep 8765 定位并停止旧进程;Windows 下用 netstat -ano | findstr 8765 定位进程号后结束该进程。

模型连接失败 对话返回网络错误或服务端 5xx 时,检查端点可达性与密钥有效性:curl -H "Authorization: Bearer <密钥>" <端点地址>/models。亦可在网页端「设置 → 模型服务」使用连接测试按钮。

首次访问无鉴权、任何人都能进入 请检查 server.auth.registration 与 server.auth_tokens:两者都未配置且库中无账号时服务不校验身份。生产环境务必启用其中之一。

SSE 无输出或中途断流 确认反向代理已设置 proxy_buffering off 并放宽读超时。

内容安全过滤未生效 检查 safety.enabled 与词表路径(相对路径基于数据目录)。词表为空时服务会在启动日志中明确告警——此时过滤机制虽已启用,但等同于未过滤,需由部署方填入自管词表。

忘记访问令牌或管理员密码 注册制账号可由其他管理员在后台管理中重置;静态令牌直接查看配置文件中 server.auth_tokens 的键。

升级失败 查看 logs/update.log;旧版程序被保留为带 .bak 后缀的备份文件,可改回文件名完成回滚。

性能不足 先确认是否为模型端点耗时所致(参考 trueagt_chat_duration_seconds 的 P95),再按第 8 节启用多副本,并按第 10.5 节评估是否切换数据库后端。

本文档随 TrueAGT 安装包一同发布;如与软件实际行为不一致,以软件当前版本为准。