环境要求与本地部署

部署形态是宿主机直接运行，不用 Docker。web 的构建产物由 Go server 托管，两个 Python 服务作为本机进程运行。

环境依赖

依赖	版本	用途	必需性
Go	1.26+	server	必需
Node.js	22+	converter 与 web 构建	必需
Python + uv	3.10+	两个编辑服务	编辑和 diff 功能必需，纯浏览可不装
Linux + bubblewrap	—	脚本沙箱	生产必需。缺失时 run/save 直接拒绝执行
ripgrep (rg)	—	chat agent 的搜索工具后端	chat agent 必需
PostgreSQL	14+	Issue 等数据的持久化	可选，默认用文件存储

几点说明：

• Python 依赖全部来自 PyPI 官方发布，uv sync 直接安装，不需要本机源码。
• bubblewrap 在 Debian/Ubuntu 上装 bubblewrap 包，RHEL 系用 dnf install bubblewrap。沙箱只有 bwrap 一条生产路径，没有它就拒绝执行，不会降级。rlimit 后端仅供测试显式选择，生产不要设。
• ripgrep 缺失时，agent 的 grep 工具会报错，只能退回逐文件读取，所以建议装上。

启动：开发环境

开四个终端，DXF 功能不需要时第四个里的 cad 服务可以不启。

# 0. 一次性：安装依赖
cd converter && npm install
cd ../web && npm install
cd ../services/ifc && uv sync
cd ../services/cad && uv sync

# 1. edit-service（:8100）—— VIEWER_DATA_DIR 必须指向 data 的绝对路径
cd services/ifc
VIEWER_DATA_DIR="$(cd ../data && pwd)" uv run uvicorn app.main:app --port 8100

# 1b. cad-edit-service（:8200）—— DXF 模型需要；纯 IFC 可不启
cd services/cad
VIEWER_DATA_DIR="$(cd ../data && pwd)" uv run uvicorn app.main:app --port 8200

# 2. Go server（:8090）
cd server && go run ./cmd/server

# 3. web（:5173）
cd web && npm run dev

打开 http://localhost:5173 即可使用。完整配置项见配置说明。沙箱的运行机制见沙箱执行环境。

生产部署

生产只有 8090 一个端口。先构建前端，再启动 server，它自己就会托管 web/dist：

# 1. 构建前端（产物在 web/dist）
cd web && npm ci && npm run build

# 2. 构建并启动 server（默认托管 ../web/dist，路径可用 webDist 或 VIEWER_WEB_DIST 修改）
cd ../server && go build -o server ./cmd/server && ./server

# 3. 启动两个编辑服务，务必绑定 127.0.0.1
cd ../services/ifc && uv sync && VIEWER_DATA_DIR=/srv/aiifc/data uv run uvicorn app.main:app --host 127.0.0.1 --port 8100
cd ../services/cad && uv sync && VIEWER_DATA_DIR=/srv/aiifc/data uv run uvicorn app.main:app --host 127.0.0.1 --port 8200

生产必须设置 VIEWER_API_TOKEN。 编辑 API 会在服务端沙箱里执行脚本，等于开放代码执行。不设 token 只适用于本机单人开发，任何对外部署都必须带上。

PostgreSQL 可选。装好 14+ 版本后给 server 传 VIEWER_PG_DSN 即可，建表自动完成：

VIEWER_PG_DSN=postgres://user:pass@127.0.0.1:5432/aiifc

systemd 最小示例

# /etc/systemd/system/aiifc-server.service
[Unit]
Description=AI_IFC Go server
After=network.target

[Service]
WorkingDirectory=/opt/AI_IFC/server
Environment=VIEWER_API_TOKEN=换成强随机串
ExecStart=/opt/AI_IFC/server/server -config server_config.json
Restart=on-failure

[Install]
WantedBy=multi-user.target

# /etc/systemd/system/aiifc-ifc.service（cad 服务同构：目录换 services/cad、端口 8200）
[Unit]
Description=AI_IFC edit-service
After=network.target

[Service]
WorkingDirectory=/opt/AI_IFC/services/ifc
Environment=VIEWER_DATA_DIR=/opt/AI_IFC/data
ExecStart=/usr/local/bin/uv run uvicorn app.main:app --host 127.0.0.1 --port 8100
Restart=on-failure

[Install]
WantedBy=multi-user.target

注意两点：两个 Python 服务的 VIEWER_DATA_DIR 必须和 server 配置里的 dataDir 指向同一个目录；server 用哪个用户跑，数据目录就要对那个用户可写。

验证

# 端到端冒烟（需 server 运行；edit-service 不可达时编辑段落自动跳过）
./scripts/smoke.sh

# 各层测试
cd server && go test ./...
cd services/ifc && uv run --group dev pytest
cd services/cad && uv run --group dev pytest
cd web && npm test
cd converter && npm test

浏览、上传、转换不依赖编辑服务和 PostgreSQL；编辑、版本、diff 需要编辑服务在运行。