面向部署者与运维人员。
| 项目 | 说明 |
|---|---|
| 文档名称 | TrueAGT 部署指南 |
| 适用对象 | 部署者与运维人员 |
| 配套文档 | 《产品介绍》《用户手册》《API 参考》《多节点协作配置指南》《数据流向声明》 |
TrueAGT 是工具,不是服务。 当你部署 TrueAGT 并向他人(尤其是社会公众)提供服务时,你就是法律意义上的「生成式人工智能服务提供者」,需自行履行相应义务。
部署完成后,以下事项需要由你(部署者/运营方)完成,TrueAGT 只提供相应的能力而不替代你的责任:
| 义务 | 落地方式 |
|---|---|
| 内容安全审核 | 启用内容安全过滤机制,并自备、维护词表;需要时叠加模型护栏与人工复核 |
| 违法内容的处置与报告 | 审计链与处置留痕记录每一条发现与处置;报告环节由人工完成并留证 |
| 生成合成内容标识 | 配置服务提供者名称与编码,保证显式标识与隐式编号可追溯到真实主体 |
| 投诉举报机制 | 页面内置举报入口,管理员需配置处理流程并对外公示联系方式与处理时限 |
| 算法备案与安全评估 | 面向公众提供服务时按主管机关要求办理 |
| 日志与留存 | 运行日志与审计记录的留存期限(相关办法要求不少于六个月)需由备份与日志轮转策略落实 |
TrueAGT 不保证部署者已合规,也不承担部署者的合规责任;同样,TrueAGT 不宣称已通过任何国家认证,也不宣称部署即等同于合规。
若不向境内公众提供服务(自用或组织内部使用),则不适用备案与安全评估义务,但个人信息保护、数据安全等一般性法律义务仍然存在。
部署完成后请复核:服务端对运行期产生的对话内容具备可发现、可处置的能力——这既是法定要求,也是正确配置的目标状态。请勿在对外宣传中声称运营方无法查看任何数据。
| 项目 | 要求 |
|---|---|
| 操作系统 | Linux / Windows / macOS |
| 运行时 | Python 3.10 及以上;Windows 安装包无需预装 Python |
| 运行时依赖 | 无第三方 Python 包,无需执行包安装命令 |
| 模型服务 | 任一 OpenAI 兼容端点 / Anthropic / Ollama,需从部署机网络可达 |
| 磁盘 | 预留会话数据库、附件与日志空间,建议不少于 1 GB |
| 端口 | 默认 8765(可在配置中调整) |
面向最终用户,全程无需安装 Python 或任何依赖:
trueagt-0.9.233-win-setup.zip;install.bat,安装完成后桌面与开始菜单出现「TrueAGT」快捷方式;http://127.0.0.1:8765)。安装位置为当前用户的 %LOCALAPPDATA%\TrueAGT,会话数据、长期记忆与日志分别位于该目录下的 data/ 与 logs/。
autostart_on.bat 开启,双击 autostart_off.bat 关闭;卸载时自动清理;config.json 并重启;uninstall.bat 并按提示确认(会删除全部聊天数据,请先备份 data/);服务器场景、容器部署、监控告警等内容见以下章节。
发布包中不包含 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 }
}
}
base_url 留空表示使用所选服务商的官方地址;自托管推理服务(如 llama.cpp、vLLM)则填写其端点;host 为 127.0.0.1 时仅本机可访问,配合反向代理使用是推荐做法;需直接对外时改为 0.0.0.0;config/config.example.json 中的注释。# 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"}
两种方式任选其一:
server.auth.registration。取值为 open(开放自助注册,第一个注册的账号自动成为管理员)、invite(需管理员发放的一次性邀请码,置于 server.auth.invite_codes)或 closed(仅由管理员在后台创建账号)。server.auth_tokens 中以「令牌: 用户名」的键值形式逐一分配,该方式下使用者以管理员身份使用。两者都未配置且数据库中无账号时,服务不校验身份,所有可达该端口的请求归入默认本地账号。内网部署也必须启用鉴权。
账号相关的默认策略(security 段):口令长度默认下限 8 位且须同时包含字母与数字;同一账号连续登录失败 5 次或同一来源地址失败 20 次即锁定 15 分钟。
以专用账号运行,不要使用 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 # 跟踪日志
其他注意事项:
config.json,并确认其中的模型端点从部署机可达;data/trueagt.db 与 data/trueagt.key(唯一解密凭据)。trueagt.key 丢失将无法解密既有数据,请与数据备份分开存放;TRUE_AGT_LOG_DIR 指向专用目录,并确保配置文件中的 server.log_dir 一致;| 形态 | 建议 |
|---|---|
| 发布包部署 | 服务器场景首选,无需构建环节、可控性最高 |
| 容器部署 | 环境一致性要求高或需要快速扩缩时的推荐方案 |
| 系统服务守护 | 与上述任一形态搭配使用 |
| Windows 安装包 | 面向最终用户的桌面场景 |
发布包内提供 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
要点:
python:3.12-slim,容器内以非特权用户 trueagt 运行;config.json 以只读方式挂载进容器;trueagt-data 卷)与日志(trueagt-logs 卷)持久化在容器卷中,升级镜像不丢失历史会话;/healthz);0.0.0.0:8765。config.json 含模型密钥,请勿提交至版本库。
同时配置 server.cert_file 与 server.key_file(PEM 格式),服务启动时即启用 HTTPS:
"server": {
"cert_file": "certs/server.crt",
"key_file": "certs/server.key"
}
两项缺一时将会警告并回退为明文 HTTP;证书加载失败时同样回退,请在启动日志中确认监听协议为 https。内网环境可使用自签证书,公网环境建议使用受信任证书或经由反向代理终结。
对话采用 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;
}
}
默认情况下后台管理页面与主对话服务共用端口。如需将管理面与业务面隔离,可启用独立管理端口:
"server": {
"admin_enabled": true,
"admin_host": "127.0.0.1",
"admin_port": 8766
}
启用后,公共端口对后台管理页面与 /api/admin/* 接口一律返回 404,后台管理仅在指定地址与端口提供。建议将该端口限制在运维网络内,并通过堡垒机或 VPN 访问。
默认单进程运行。单进程吞吐不足时,可部署多个副本共享同一份存储:
"server": { "distributed": true }
启用后将发生三处变化:
部署要点:
"distributed": true 并使用不同端口;upstream trueagt {
ip_hash;
server 127.0.0.1:8761;
server 127.0.0.1:8762;
}
限制:SQLite 写入并发能力有限,多副本适合中小规模(数十并发用户的量级)。更大规模建议将存储后端切换为 PostgreSQL(见 10.5 节)。
控制面与数据面分离:中央协调器负责节点注册、令牌签发、任务中转与用量上报,不生成人工智能内容;各节点承担实际的模型调用与内容生成,业务数据留在本地节点。节点以客户端身份主动连接协调器,无需公网地址或开放入站端口。
在协调器侧:
"collab": { "enabled": true }
在节点侧:
"collab": {
"coordinator_url": "https://coord.example.com",
"coordinator_token": "协调器上的用户令牌",
"node_label": "办公工作站",
"node_execution_enabled": true
}
协作相关的配置项在服务启动时读取,修改后需重启方能生效。详细的字段说明、连通性验证与故障排查见《多节点协作配置指南》。
跨用户协作开关(allow_cross_user)默认为关闭,适用于「用户自托管中央 + 内网 + 非面向公众」的形态;开启前请完成自身合规评估,并确认该形态不会使部署者成为面向公众的服务提供者。
| 数据 | 默认位置 | 说明 |
|---|---|---|
| 会话数据库 | data/trueagt.db | 会话、消息、事件与用量(密文落盘) |
| 长期记忆 | data/users/<账号>/memory.json | 按账号隔离(密文落盘) |
| 加密密钥 | data/trueagt.key | 唯一解密凭据,须单独备份,不随备份或迁移外传 |
| 运行日志 | logs/trueagt.log | 按大小轮转 |
| 审计记录 | data/audit_chain*.json | 防篡改哈希链,分段归档 |
"security": {
"encryption": {
"enabled": true,
"algorithm": "chacha20",
"key_file": "data/trueagt.key"
}
}
algorithm 取 chacha20(默认,ChaCha20 + HMAC-SHA256)或 sm4(国密 SM4 + HMAC-SM3,供密评与等保场景选用)。切换算法后已有密文不会自动重写,请在新部署时确定;security.encryption.passphrase_env / passphrase / passphrase_rounds):以口令包裹主密钥,即使密钥文件丢失也可凭口令恢复,建议优先从环境变量注入口令。"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/(密钥文件留在原位或一并恢复)→ 启动服务 → 抽查历史会话可正常加载。
"server": {
"storage": {
"type": "webdav",
"webdav": {
"url": "https://dav.example.com/trueagt",
"username": "账号",
"password": "口令",
"sync_interval": 15
}
}
}
支持任何兼容 WebDAV 的网盘(如自建 Nextcloud、坚果云等)。云盘不可达时会以本地缓存继续运行并在日志中告警,恢复后自动续同步。切换存储位置也可在网页端「设置 → 数据存储」中完成,无需重启。
"database": {
"backend": "postgresql",
"pg_dsn": "host=127.0.0.1 port=5432 dbname=trueagt user=trueagt password=***"
}
需要先安装相应的数据库驱动;驱动缺失时会自动回退 SQLite 并记录日志,不会阻断启动。切换后端后请重启服务并完整验证。注意:已有数据不会自动迁移,需由运维自行导出导入。
"marking": {
"enabled": true,
"provider": "贵方在服务协议与算法备案中使用的主体名称",
"provider_code": "YOURCODE",
"secret": "env:TRUE_AGT_MARKING_SECRET"
}
provider 与 provider_code 用于生成隐式标识与内容编号前缀,必须替换为你自己的主体名称与编码,否则内容编号无法追溯到真实主体;secret 为内容编号的 HMAC 密钥,建议从环境变量注入;留空则编号不带防伪造标签;轮换密钥会导致旧编号无法验证,请与留存期限一并规划。服务内置指标端点 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_total | Counter | HTTP 请求计数(按路径、状态码) |
trueagt_http_duration_seconds | Histogram | HTTP 请求耗时分布 |
trueagt_chat_total | Counter | 对话执行总数 |
trueagt_chat_errors_total | Counter | 对话执行失败总数 |
trueagt_chat_cancelled_total | Counter | 对话被取消总数 |
trueagt_chat_duration_seconds | Histogram | 对话端到端耗时分布 |
trueagt_tokens_total | Counter | Token 消耗(按输入/输出方向) |
trueagt_sessions_total | Gauge | 会话总数 |
trueagt_active_users | Gauge | 正在执行对话的用户数 |
trueagt_uptime_seconds | Gauge | 进程运行时长 |
将 Prometheus 作为数据源导入图形面板软件即可得到可视化看板。
不搭建监控栈时,可启用内置巡检:按设定间隔检查磁盘剩余空间、可用内存、错误日志增量、授权到期与登录失败次数,达到指定级别的告警推送到群机器人。服务启动、停止与异常退出同样会通知。
"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
}
}
format 支持 wecom(企业微信)、dingtalk(钉钉,加签密钥填 secret)、feishu(飞书)与 generic(通用 JSON POST);GET /api/alerts 查看最近的告警与统计;本地记录不受推送级别影响。运行日志按大小轮转,级别可通过 server.log_level 调整。除进程日志外,以下记录为合规所需,请勿关闭并纳入备份:
GET /api/audit/verify 校验完整性;请结合轮转与备份策略确保上述记录的留存期限满足适用法规要求。
适用于「统一管理多个实例的账号」的拓扑:由一台实例担任注册服务器,其余实例将账号校验指向它。
"server": {
"auth": {
"mode": "remote",
"remote_url": "https://auth.example.com:8765",
"verify_interval_hours": 24,
"offline_grace_hours": 168
}
}
verify_interval_hours 向注册服务器复核:账号被停用或删除时本地会话立即失效;注册服务器不可达时,已登录会话在宽限期内继续可用;需要注意的是,账号数据在注册服务器上的处理由注册服务器的运营方负责;各实例的对话数据仍在实例本机,这一点不因采用该模式而改变。
对外分发时启用试用与授权码管控:
"server": {
"license": {
"enabled": true,
"file": "data/license.key"
}
}
POST /api/license/activate;enabled 设为 false 关闭管控。data/、logs/、config.json 保持原位);容器部署则更新镜像后重启;发布包部署不支持应用内自动升级(相关接口会明确返回错误),请替换为新版发布包完成更新。
由你自己分发升级时,先在发布机上生成清单:
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"
}
}
auto:后台按间隔检查,发现新版本自动下载、校验并完成替换与重启;manual(默认):仅在「设置 → 关于与升级」中手动检查并执行;off:关闭检查。升级流程为下载 → SHA256 校验 → 生成后台替换脚本 → 主进程退出 → 备份旧版程序 → 替换文件(config.json、data/、logs/ 原样保留)→ 按原参数重启,全过程记录于 logs/update.log。命令行亦可直接使用:
TrueAGT.exe --check-update # 仅检查
TrueAGT.exe --upgrade # 检查并升级
端口被占用 启动时报 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 节评估是否切换数据库后端。