#服装行业标准模型快速操作手册

本文用于指导客户从零落地 DataAgent 服装行业标准模型，适用于新环境首次部署和行业标准包交付实施。按照本文操作，可以完成系统部署、标准模型导入、企业数据接入、Schema 学习、用户权限配置以及上线前验证。

本文不是通用的 DataAgent 部署说明。服装行业标准模型使用专用的数据库和 Compose 配置，部署时请以本文附录 B 提供的最终版 docker-compose.yml 为准。

阅读方式

按目录顺序操作即可。部署由运维人员完成，模型和权限由系统管理员完成，企业数据由数据工程师导入。

#目录与快速流程

整个实施流程可以概括为 6 步：

• 1. 开始前准备
• 2. 使用 docker-compose.yml 部署系统
• 3. 首次登录与初始化
• 4. 导入行业标准包
• 5. 导入企业数据
• 6. 学习模型并开始使用
• 7. 用户权限和同义词
• 8. 常见问题与上线检查
• 附录 A　数据模型总览与字段字典
• 附录 B　Docker Compose 完整配置
• 附录 C　行业标准包内容说明

#1. 开始前准备

#1.1 需要准备的资源

• 一台满足单机部署要求的 Linux 服务器。
• 可用的大模型 API 和嵌入向量 API。
• docker-compose.yml、行业标准包 ZIP 和数据字典 Excel。行业标准包请联系我司项目对接人员获取，本文不提供下载。
• 可连接 ClickHouse 的 ETL 工具。
• 服务器 IP 和系统码，用于申请许可证。

详细说明：服务器、服务组件与大模型技术要求

详细说明：环境准备与首次使用说明

#1.2 谁来操作

重要

本手册包含默认初始化账号和行业标准包约定的数据库密码。投产前必须修改 admin 密码；CLICKHOUSE_PASSWORD 为标准包固定值，不要修改，并限制数据库端口的访问范围。

#2. 使用 docker-compose.yml 部署系统

本章目标

使用本文附录 B提供的最终版 docker-compose.yml，修改必须的配置，启动 4 个服务，并确认网页可以正常访问。

#2.1 创建部署目录并上传文件

建议为系统建立独立目录。以下以 /yiask 为例；如客户有统一目录规范，可替换为实际路径。

mkdir -p /yiask
cd /yiask
# 将附录 B 的最终版配置保存为 docker-compose.yml，并上传到当前目录
ls -l docker-compose.yml

最后一条命令应能看到 docker-compose.yml。文件名不要增加 .txt，保存编码建议使用 UTF-8。

#2.2 检查 Docker 环境

docker --version
docker compose version

两条命令都能显示版本号后再继续。如果提示 command not found，请先安装 Docker 和 Docker Compose 插件。本方案的 Compose 配置与通用单服务器部署配置不同，请始终使用本文附录 B 的最终版本。

#2.3 先看懂配置文件中的关键项

详细说明：Docker 部署环境变量说明

#2.4 生成并填写 APP_KEY

在服务器执行：

openssl rand -base64 32

复制命令输出，打开 docker-compose.yml，找到下面这一行：

- APP_KEY=your-random-app-key-here

将等号右侧替换为刚生成的随机值。修改后可执行以下命令确认占位符已被替换：

grep -n "APP_KEY" docker-compose.yml
grep -n "your-random-app-key-here" docker-compose.yml

正确结果

第一条命令能看到新的 APP_KEY；第二条命令没有输出。APP_KEY 应妥善保存，同一环境启动后不要无计划更换。

#2.5 检查配置格式

docker compose config

该命令用于检查 YAML 缩进、引号和配置格式。没有报错并能输出完整配置时，再执行启动命令。编辑 YAML 时使用空格缩进，不要使用 Tab。

#2.6 拉取镜像并启动

docker compose pull
docker compose up -d
docker compose ps

系统会启动 DataAgent、PostgreSQL、Redis 和 ClickHouse 4 个服务。第一次拉取镜像和初始化可能需要几分钟。

#2.7 查看日志并判断成功

docker compose logs -f --tail=200 app

日志出现以下内容时，表示应用已启动：

PM2 log: App [index:0] starting in -cluster mode-

按 Ctrl+C 退出日志查看不会停止容器。首次初始化通常约 5 分钟。

• docker compose ps 显示 4 个容器均在运行。
• 浏览器可以打开 http://<server-ip>:3052。
• 服务器防火墙或安全组已放通必要端口。

#2.8 端口说明

#2.9 常见问题

不要执行

不要随意运行 docker compose down -v。参数 -v 会删除 Docker 数据卷，可能导致系统配置和数据库数据丢失。

#3. 首次登录与初始化

#3.1 登录系统

安全要求

首次登录后立即修改 admin 密码。

#3.2 完成首次配置

1. 向我方技术人员提供服务器 IP 和系统码。
2. 获取并填写许可证。
3. 填写大模型 API。
4. 填写嵌入向量 API。
5. 保存配置并确认进入系统主界面。

#3.3 完成检查

• 许可证状态正常。
• 大模型和嵌入向量 API 测试通过。
• admin 密码已经修改。

详细说明：大模型与嵌入向量模型可用性测试

#4. 导入行业标准包

#4.1 选择文件

行业标准包不在本文提供下载，请联系我司项目对接人员获取。收到交付文件后，直接使用原始的 yiask-apparel-model-v20260802.zip，不要解压、修改或重新打包。

#4.2 进入导入入口

进入“系统搭建 > 业务知识建模 > 语义建模 > Schema 列表”，点击“导入建模包”。

图 1　点击“导入建模包”（红色箭头位置）

#4.3 导入并检查

1. 选择行业标准包 ZIP 并开始导入。
2. 等待约 10 分钟，不要重复提交。
3. 导入后确认 Schema 列表中有 17 个 Schema。
4. 进入“业务知识图谱”并点击刷新。

正确结果

应看到 14 个实体和 3 个事件。若数量不一致，先查看任务状态和应用日志。

详细说明：建模数据导入和导出说明

#5. 导入企业数据

#5.1 数据库连接

投产前

CLICKHOUSE_PASSWORD 是服装行业标准包的固定值，不要修改；ETL 连接必须使用该值。数据库端口不要暴露到公网。

详细说明：模型连接数据库操作说明

#5.2 建议导入顺序

行业包预置数据

geo 和 calendar 已包含在行业标准包中，无需导入。企业数据中的 geo_id 和 calendar 应关联行业包已有的 ID。仅当企业需要增加财年数据时，才补充或更新 calendar 中的财年字段。

#5.3 导入时只需注意 5 点

• 主键 id 必须唯一且长期保持不变。
• 关联字段必须填写目标表中真实存在的 id。
• geo 和 calendar 使用行业包预置数据，不要重复导入；需要增加财年数据时除外。
• 先导入主数据，再导入销售和库存等事件数据。
• Excel 与实际表结构不一致时，以 ClickHouse 实际字段类型为准；sales_target 当前没有 SKU 字段，按现有物理字段导入。

#6. 学习模型并开始使用

#6.1 学习全部 Schema

企业数据导入后，进入“系统搭建 > 业务知识建模 > 语义建模 > 学习所有 Schema > 开始学习”。

1. 确认 17 个 Schema 均在列表中。
2. 点击“学习所有 Schema”。
3. 点击“开始学习”并等待任务完成。

详细说明：业务建模与 Schema 学习说明

#6.2 首轮测试

• 今年销售额多少？

判断标准

问题有结果，关键数值能与源系统对账，权限用户看到的数据范围正确。

#7. 用户权限和同义词

#7.1 默认角色

创建用户前，先确认 employee 和 store_warehouse 数据已导入且关联正确。

详细说明：角色与数据权限配置说明

#7.2 客户术语不一致怎么办

不要直接修改标准模型。进入“系统搭建 > 全局同义词”，补充客户内部叫法。

详细说明：同义词配置说明

#8. 常见问题与上线检查

#8.1 常见问题

详细说明：问答异常排查说明

#8.2 上线前确认

• 4 个容器运行正常。
• admin 密码已修改；CLICKHOUSE_PASSWORD 保持标准包固定值。
• 17 个 Schema 导入完整。
• 企业数据导入并完成关键数据对账。
• 全部 Schema 学习完成。
• 导购、店长和集团权限验证通过。
• 配置文件和 Docker 数据卷已备份。

详细说明：生产环境备份说明

#附录 A　数据模型总览与字段字典

#A.1 模型总览

当前版本

标准包包含 17 个 Schema，其中 14 个实体、3 个事件，共 130 个属性。字段类型为导入建议；最终以 ClickHouse 实际表结构为准。

#A.2 物理字段字典

下表保留原 Excel 中有意义的字段名、中文名称、建议类型、关联和备注。源表中作为占位符的“8”未重复展示。

#sku｜SKU（实体）

#skc｜SKC（实体）

#spu｜SPU（实体）

#series｜系列（实体）

#category｜品类（实体）

#brand｜品牌（实体）

#color｜颜色（实体）

#organization｜组织（实体）

#channel｜渠道（实体）

#geo｜地理位置（实体）

#employee｜员工（实体）

#store_warehouse｜店仓（实体）

#member｜用户（实体）

#calendar｜日历（实体）

#sales_order_line｜销售（事件）

#sales_target｜销售目标（事件）

#inventory_snapshot｜库存快照（事件）

#附录 B　Docker Compose 完整配置

#B.1 关键配置说明

复制说明

以下是服装行业标准模型方案使用的最终版配置。请将其完整保存为 docker-compose.yml，不要替换为通用单服务器部署配置。

#B.2 完整配置

name: yiask

services:
  app:
    image: docker.1ms.run/yiask/dataagent:2.3.6
    # pull_policy: always
    container_name: yiask
    environment:
      - PROJECT=yiask
      - LOGGER_LEVEL=warn
      - TZ=Asia/Shanghai
      # APP_KEY 用于 JWT token 签名验证，必须随机生成且保持固定（长度、格式无特殊要求。示例生成指令：openssl rand -base64 32）
      - APP_KEY=your-random-app-key-here

      # PG 元数据库配置
      - DB_HOST=postgres
      - DB_DATABASE=yiask_meta_store
      - DB_USER=postgres
      - DB_PASSWORD=postgres

      # 缓存配置（可选，默认使用内存缓存）
      - CACHE_DEFAULT_STORE=redis

      # 多进程状态同步（生产环境必选，单机 Redis 示例）
      - REDIS_URL=redis://redis:6379/0

      # 网页搜索 API Key（可选）
      # - WEB_SEARCH_API_KEY=tvly-dev-xxxxxxxx
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost/api/v1/__health_check"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s
    volumes:
      - storage:/app/nocobase/storage
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
      clickhouse:
        condition: service_started
    ports:
      - "3052:80"
    init: true
    extra_hosts:
      - "host.docker.internal:host-gateway"

  postgres:
    container_name: yiask_postgres
    image: docker.1ms.run/pgvector/pgvector:pg17-trixie
    restart: always
    command: postgres -c wal_level=logical -c max_connections=500
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 10
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: yiask_meta_store
    volumes:
      - pg-data:/var/lib/postgresql/data

  redis:
    container_name: yiask_redis
    image: docker.1ms.run/redis:8.4
    restart: always
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 10
    volumes:
      - redis-data:/data

  clickhouse:
    container_name: yiask_clickhouse
    restart: always
    ulimits:
      nofile: 262144
    image: docker.1ms.run/clickhouse:lts
    volumes:
      - ck_vol:/var/lib/clickhouse
    environment:
      CLICKHOUSE_USER: yiask_admin
      CLICKHOUSE_PASSWORD: "Yw7!Kq9@Vx2#Lm8^Rz4_Nc6P"
      CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
    ports:
      - '9000:9000'
      - '8123:8123'
    command:
      - bash
      - -c
      - |
        mkdir -p /docker-entrypoint-initdb.d

        cat > /docker-entrypoint-initdb.d/init.sql <<'EOF'
        CREATE DATABASE IF NOT EXISTS yiask_scene_apparel;

        EOF

        exec /entrypoint.sh

volumes:
  storage:
  pg-data:
  redis-data:
  ck_vol:

#附录 C　行业标准包内容说明

#建模数据内容统计