数据库、Redis 和存储

本页涵盖数据层：SQL 数据库、Redis 和文件存储。在 AI 服务容器启动前，这些组件必须处于运行状态且可访问——服务会在启动时连接到这些组件，若无法连接则无法继续运行。

• SQL 数据库：存储配置、对话、文件和文档等持久化数据。

• Redis：用于缓存与协调（SSE 推送、速率限制、发布/订阅）。可确保 AI 服务保持无状态。

• 文件存储：存储上传的文件与文档。

请先配置数据层，再继续配置 LLM providers 和 JWT authentication。有关容器运行时、反向代理、Transport Layer Security (TLS)、Kubernetes 以及 ECS 部署的内容，请参阅 Production deployment guide。

支持的版本

组件	最低版本	推荐版本	备注
MySQL	8.0	8.0.x（最新补丁版本）	固定使用 mysql:8.0。请参阅 MySQL 文档。
PostgreSQL	13	16
Redis	3.2.6	7.x	可通过 REDIS_CLUSTER_NODES 和 REDIS_TLS_ENABLE 支持 Redis Cluster 与 TLS。

AI 服务对 MySQL 和 PostgreSQL 的支持程度一致。可选择运维团队已在使用的版本。

选择部署路径

评估阶段可使用 Docker Compose，生产环境则建议使用托管云服务（Amazon RDS、Cloud SQL、Azure Database）。

PostgreSQL schema 前提条件

本节仅适用于 PostgreSQL 部署。MySQL 部署可跳转至“版本固定”章节。

AI 服务要求存在名为 cs-on-premises（含连字符）的 schema。若该 schema 不存在，容器将在首次启动时崩溃，并显示：

[FATAL] PostgreSQL Error: schema "cs-on-premises" does not exist

请在首次启动 AI 服务之前应用以下任一修复方法。

选项 A：预创建 schema

双引号为必填，因为 schema 名称中包含连字符。

CREATE SCHEMA "cs-on-premises";

可在 psql 中使用 \dn 进行验证。cs-on-premises 应出现在列表中。

选项 B：使用默认的 public schema

在 AI 服务容器上设置 DATABASE_SCHEMA 环境变量：

DATABASE_SCHEMA=public

此方法完全绕过带连字符的 schema。MySQL 部署无需此步骤——数据库名称（DATABASE_DATABASE）即作为命名空间。

版本固定

请为所有数据层镜像固定特定主版本（mysql:8.0、postgres:16、redis:7）。使用 :latest 或 :8 等浮动标签可能在常规镜像拉取过程中引入破坏性变更。

MySQL

请不要使用 mysql:8。该标签现指向 MySQL 8.4，已移除 default-authentication-plugin 服务器选项。若以 --default-authentication-plugin=mysql_native_password 启动 MySQL 容器（如部分旧版 Compose 文件和清单所采用的方式），容器将启动失败并反复重启，报错如下：

[ERROR] [MY-000067] [Server] unknown variable 'default-authentication-plugin=mysql_native_password'.
[ERROR] [MY-010119] [Server] Aborting

AI 服务使用 MySQL 8.0 默认认证插件进行连接，因此无需该选项；本页示例均未设置此项。

请在所有清单（docker run、Docker Compose、Kubernetes、Helm、ECS）中固定使用 mysql:8.0。使用更新的 MySQL 版本并通过变通方案（移除该标志并切换至 caching_sha2_password）运行，不属于受支持的配置。

数据库用户权限

首次启动时，AI 服务将执行 schema 迁移，并在以下命名空间中创建约 32 张表：ai_assistant_*、environments_*、security_*、insights_*、blob_storage_* 以及 cs_migrations*。

数据库用户需具备足够的权限，以创建、修改及操作这些表。

MySQL

CREATE USER 'ai_service'@'%' IDENTIFIED BY '<strong-password>';
GRANT SELECT, INSERT, UPDATE, DELETE,
      ALTER, CREATE, DROP, INDEX,
      TRIGGER, LOCK TABLES, REFERENCES
  ON ai_service.* TO 'ai_service'@'%';
FLUSH PRIVILEGES;

开发环境快捷方式

GRANT ALL PRIVILEGES ON ai_service.* TO 'ai_service'@'%';

请将权限授予 AI 服务数据库本身（ON ai_service.），如上述语句所示。启动检查不接受全局授予的权限（ON *.）或通过角色继承的权限：即使用户拥有所有列出的权限，服务仍会停止并显示 Not enough permissions to access database. Missing privileges: …​

在 Cloud SQL MySQL 上，默认用户通过 cloudsqlsuperuser 角色拥有其权限。在首次启动前，请为服务用户运行数据库范围的 GRANT 语句。

PostgreSQL

如果选择了 DATABASE_SCHEMA=public（参见 PostgreSQL schema 前提条件），请将以下每条语句中的 public 替换为 "cs-on-premises"。

CREATE USER ai_service WITH PASSWORD '<strong-password>';
CREATE DATABASE ai_service OWNER ai_service;
\c ai_service
CREATE SCHEMA "cs-on-premises" AUTHORIZATION ai_service;
GRANT CREATE, USAGE ON SCHEMA "cs-on-premises" TO ai_service;
GRANT ALL ON ALL TABLES IN SCHEMA "cs-on-premises" TO ai_service;
GRANT ALL ON ALL SEQUENCES IN SCHEMA "cs-on-premises" TO ai_service;
ALTER DEFAULT PRIVILEGES IN SCHEMA "cs-on-premises"
  GRANT ALL ON TABLES TO ai_service;
ALTER DEFAULT PRIVILEGES IN SCHEMA "cs-on-premises"
  GRANT ALL ON SEQUENCES TO ai_service;

开发快捷方式

GRANT ALL ON SCHEMA "cs-on-premises" TO ai_service;

托管式 PostgreSQL 的 TLS 问题：Amazon RDS、Cloud SQL 和 Azure Database for PostgreSQL 默认要求 TLS（rds.force_ssl=1 / require_secure_transport=ON）。当强制执行 TLS 且未为 AI 服务配置 DATABASE_SSL_CA 时，连接会被拒绝——但错误消息会显示为通用的“权限”错误，而不是 TLS 错误。如果在确认授权后服务仍因权限相关的数据库错误而无法启动，请检查 TLS 是否是潜在原因。

数据库设置

以下各节为每个数据库引擎提供了可直接使用的配置。本地评估请使用 Docker Compose 文件；生产环境请配置托管数据库服务（Amazon RDS、Azure Database、Cloud SQL），并通过环境变量传递连接详细信息（参见 Connecting the AI service）。

Docker Compose（推荐用于评估）

MySQL Compose 文件

services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: <root-password>
      MYSQL_DATABASE: ai_service
      MYSQL_USER: ai_service
      MYSQL_PASSWORD: <strong-password>
    ports:
      - "3306:3306"
    volumes:
      - mysql_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7
    ports:
      - "6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  mysql_data:

PostgreSQL Compose 文件

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: ai_service
      POSTGRES_USER: ai_service
      POSTGRES_PASSWORD: <strong-password>
    ports:
      - "5432:5432"
    volumes:
      - pg_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ai_service -d ai_service"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7
    ports:
      - "6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  pg_data:

如果使用 PostgreSQL 且未使用 DATABASE_SCHEMA=public，在执行 docker compose up -d 后，请创建 schema：

docker compose exec postgres psql -U ai_service -d ai_service \ -c 'CREATE SCHEMA "cs-on-premises";'

Docker 单容器（不使用 Compose）

当无法使用 Docker Compose 或需要集成到现有编排脚本中时，请使用这些 docker run 命令。

MySQL

docker run -d \
  --name ai-mysql \
  -e MYSQL_ROOT_PASSWORD=<root-password> \
  -e MYSQL_DATABASE=ai_service \
  -e MYSQL_USER=ai_service \
  -e MYSQL_PASSWORD=<strong-password> \
  -p 3306:3306 \
  -v ai_mysql_data:/var/lib/mysql \
  mysql:8.0

PostgreSQL

docker run -d \
  --name ai-postgres \
  -e POSTGRES_DB=ai_service \
  -e POSTGRES_USER=ai_service \
  -e POSTGRES_PASSWORD=<strong-password> \
  -p 5432:5432 \
  -v ai_pg_data:/var/lib/postgresql/data \
  postgres:16

然后创建 schema：

docker exec -i ai-postgres psql -U ai_service -d ai_service \ -c 'CREATE SCHEMA "cs-on-premises";'

对于 Podman，请将所有 docker 替换为 podman。在无根（rootless）Podman 上，请使用命名卷而非绑定挂载的宿主机路径，以避免 SELinux 和 UID 映射问题。

原生安装（macOS）

macOS 上的 MySQL 和 PostgreSQL

MySQL：

brew install mysql
brew services start mysql
mysql_secure_installation
mysql -u root -p <<'SQL'
CREATE DATABASE ai_service;
CREATE USER 'ai_service'@'%' IDENTIFIED BY '<strong-password>';
GRANT SELECT, INSERT, UPDATE, DELETE, ALTER, CREATE, DROP,
      INDEX, TRIGGER, LOCK TABLES, REFERENCES
  ON ai_service.* TO 'ai_service'@'%';
FLUSH PRIVILEGES;
SQL

PostgreSQL：

brew install postgresql@16
brew services start postgresql@16
createuser -P ai_service
createdb -O ai_service ai_service
psql -d ai_service -c 'CREATE SCHEMA "cs-on-premises" AUTHORIZATION ai_service;'

验证所有服务是否正在运行：

brew services list

原生安装（Linux）

Debian/Ubuntu 上的 MySQL 和 PostgreSQL

MySQL：

sudo apt update
sudo apt install -y mysql-server
sudo systemctl enable --now mysql
sudo mysql_secure_installation
sudo mysql <<'SQL'
CREATE DATABASE ai_service;
CREATE USER 'ai_service'@'%' IDENTIFIED BY '<strong-password>';
GRANT SELECT, INSERT, UPDATE, DELETE, ALTER, CREATE, DROP,
      INDEX, TRIGGER, LOCK TABLES, REFERENCES
  ON ai_service.* TO 'ai_service'@'%';
FLUSH PRIVILEGES;
SQL

若要允许远程连接，请编辑 /etc/mysql/mysql.conf.d/mysqld.cnf，将 bind-address = 0.0.0.0，然后使用 sudo systemctl restart mysql 重启。

PostgreSQL:

sudo apt update
sudo apt install -y postgresql postgresql-contrib
sudo systemctl enable --now postgresql
sudo -u postgres psql <<'SQL'
CREATE USER ai_service WITH PASSWORD '<strong-password>';
CREATE DATABASE ai_service OWNER ai_service;
SQL
sudo -u postgres psql -d ai_service \
  -c 'CREATE SCHEMA "cs-on-premises" AUTHORIZATION ai_service;'

若要允许远程连接，请编辑 /etc/postgresql/16/main/postgresql.conf (listen_addresses = '*') 并添加到 /etc/postgresql/16/main/pg_hba.conf:

host    ai_service    ai_service    0.0.0.0/0    scram-sha-256

使用 sudo systemctl restart postgresql 重启。

托管云

AI 服务会自动处理 schema 迁移。前置步骤如下：

1. 预配数据库实例 (RDS、Cloud SQL 或 Azure Database)。

2. 创建数据库 (ai_service)。

3. 创建具有“数据库用户权限”中所述权限的专用用户。

4. 仅限 PostgreSQL： 创建 cs-on-premises schema 或设置 DATABASE_SCHEMA=public。

5. 为 AI 服务开放端口 3306 (MySQL) 或 5432 (PostgreSQL) 的安全组或防火墙。

提供商	MySQL	PostgreSQL	Redis
AWS	RDS for MySQL	RDS for PostgreSQL	ElastiCache for Redis
GCP	Cloud SQL (MySQL)	Cloud SQL (PostgreSQL)	Memorystore for Redis
Azure	Azure Database for MySQL	Azure Database for PostgreSQL	Azure Cache for Redis

对于生产环境，请启用 Multi-AZ (或等效的 zonal redundancy) 和自动备份。

托管数据库 TLS

托管 PostgreSQL 服务默认要求 TLS 连接：

• AWS RDS: rds.force_ssl=1 (新实例的默认设置)

• Azure Database for PostgreSQL Flexible Server: require_secure_transport=ON (默认)

• Google Cloud SQL: 除非明确禁用，否则要求 TLS

如果没有配置 TLS，AI 服务连接会因通用错误而失败（通常报告为“权限”问题）。请使用提供商的 CA 证书包配置 DATABASE_SSL_CA：

# AWS RDS
DATABASE_SSL_CA=/certs/rds-combined-ca-bundle.pem

# Azure Database for PostgreSQL
DATABASE_SSL_CA=/certs/DigiCertGlobalRootG2.crt.pem

# Google Cloud SQL (when not using Cloud SQL Auth Proxy)
DATABASE_SSL_CA=/certs/server-ca.pem

将证书文件挂载到容器中，并在 DATABASE_SSL_CA 中引用路径。从云提供商文档下载 CA 包。

大多数托管数据库服务仅需要 CA 证书 (DATABASE_SSL_CA) 进行服务器验证。 DATABASE_SSL_CERT 和 DATABASE_SSL_KEY 仅在双向 TLS (mTLS) 时才需要。

如果托管数据库需要 TLS 但未设置 DATABASE_SSL_CA，AI 服务会记录未提及 TLS 的连接错误。在排查托管服务的连接故障时，请首先验证数据库的 TLS 设置。

从 Docker 连接到主机本地数据库

当 AI 服务在 Docker 中运行，但数据库或 Redis 在主机上原生运行时，容器必须解析主机的 IP 地址。

Docker Desktop (macOS, Windows) 和 Podman 4+ 会自动注入 host.docker.internal。

原生 Linux Docker 不会。请显式添加 host-gateway：

services:
  ai-service:
    image: registry.containers.tiny.cloud/ai-service-tiny:latest
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      DATABASE_HOST: host.docker.internal
      REDIS_HOST: host.docker.internal

或使用 docker run：

docker run --add-host=host.docker.internal:host-gateway ...

Redis

每个 AI 服务实例都必须能够访问 Redis。Redis 用于保存会话协调、Server-Sent Events (SSE) 传递和速率限制状态。临时的 Redis 中断会降低流式传输性能，但不会破坏持久数据。

设置

使用 Docker Compose 文件时，Redis 通常与数据库一起包含（见上述 compose 示例）。对于独立设置：

docker run -d --name ai-redis -p 6379:6379 -v ai_redis_data:/data redis:7

macOS / Linux 原生安装

macOS:

brew install redis
brew services start redis

Linux (Debian/Ubuntu):

sudo apt install -y redis-server
sudo systemctl enable --now redis-server

连接变量

变量	是否必需	描述
REDIS_HOST	是	主机名
REDIS_PORT	否	默认 6379
REDIS_PASSWORD	否	密码
REDIS_USER	否	用户名（Redis 6+ ACL）
REDIS_DB	否	数据库编号（默认 1）
REDIS_IP_FAMILY	否	设置为 6 以使用 IPv6

TLS

变量	描述
REDIS_TLS_ENABLE	设置为 true 以启用 TLS
REDIS_TLS_CA	CA 证书路径
REDIS_TLS_KEY	客户端密钥路径
REDIS_TLS_CERT	客户端证书路径

集群

变量	描述
REDIS_CLUSTER_NODES	以逗号分隔的 host:port[:password] 列表
REDIS_IP_FAMILY	设置为 6 以使用 IPv6 域名

集群示例

# 标准集群
REDIS_CLUSTER_NODES="redis1.example.com:7000,redis2.example.com:7001,redis3.example.com:7002"

# 带各节点密码的集群
REDIS_CLUSTER_NODES="redis1.example.com:7000:pass1,redis2.example.com:7001:pass2"

# IPv6 集群
REDIS_IP_FAMILY=6
REDIS_CLUSTER_NODES="[::1]:7000,[::1]:7001,[::1]:7002"

在生产环境中，务必设置 REDIS_PASSWORD 或使用启用了身份验证的托管 Redis 实例。

文件存储

与 SQL 数据库分开，AI 服务会持久化存储用户上传的文件（附件、图片）。存储后端由 STORAGE_DRIVER 环境变量选择。

驱动	使用场景	备注
database	演示和最小的部署	将文件存储为 SQL blob。总容量上限约为 4 GB。无需额外配置。
filesystem	具有持久卷的单实例	需要可写的挂载卷。参见 Filesystem。
s3	AWS 生产环境，或 S3 兼容（MinIO、Wasabi）	使用同一区域的存储桶。
azure	Azure 生产环境	Azure Blob Storage。

S3

STORAGE_DRIVER=s3
STORAGE_REGION=us-east-1
STORAGE_ACCESS_KEY_ID=ACCESS_KEY
STORAGE_SECRET_ACCESS_KEY=SECRET_KEY
STORAGE_BUCKET=BUCKET_NAME
STORAGE_ENDPOINT=https://custom-s3-endpoint   # 可选，用于 S3 兼容服务

S3 访问密钥需要对目标存储桶具有读取、写入、删除和列出权限。对于生产环境，启用存储桶版本控制和服务器端加密（SSE-S3 或 SSE-KMS）。

正确的变量名是 STORAGE_BUCKET 和 STORAGE_REGION，而不是 STORAGE_S3_BUCKET 或 STORAGE_S3_REGION。

Azure Blob

STORAGE_DRIVER=azure
STORAGE_ACCOUNT_NAME=ACCOUNT_NAME
STORAGE_ACCOUNT_KEY=ACCOUNT_KEY
STORAGE_CONTAINER=CONTAINER_NAME
STORAGE_ENDPOINT=https://custom-endpoint       # 可选

Filesystem

STORAGE_DRIVER=filesystem
STORAGE_LOCATION=/tmp/ai-storage

AI 服务容器以非 root 用户运行。挂载一个可写的卷，并将 STORAGE_LOCATION 指向挂载路径（例如，-v ./ai-storage:/tmp/ai-storage）。

Database

STORAGE_DRIVER=database

文件以 blob 形式存储在 SQL 数据库中，总容量上限约为 4 GB。这是用于初始评估的最简单选项。

连接 AI 服务

在配置好数据库和 Redis 后，通过环境变量将连接详细信息传递给 AI 服务容器。

MySQL 连接

-e DATABASE_DRIVER='mysql' \
-e DATABASE_HOST='mysql' \
-e DATABASE_PORT='3306' \
-e DATABASE_USER='ai_service' \
-e DATABASE_PASSWORD='<strong-password>' \
-e DATABASE_DATABASE='ai_service' \
-e REDIS_HOST='redis' \
-e REDIS_PORT='6379'

PostgreSQL 连接

-e DATABASE_DRIVER='postgres' \
-e DATABASE_HOST='postgres' \
-e DATABASE_PORT='5432' \
-e DATABASE_USER='ai_service' \
-e DATABASE_PASSWORD='<strong-password>' \
-e DATABASE_DATABASE='ai_service' \
-e DATABASE_SCHEMA='cs-on-premises' \
-e REDIS_HOST='redis' \
-e REDIS_PORT='6379'

如果未创建 cs-on-premises schema，请将 DATABASE_SCHEMA 设置为 public。参见 PostgreSQL schema 前提条件。

带有 TLS 的托管云

当连接到托管数据库服务（Amazon RDS、Azure Database、Cloud SQL）时，添加 TLS 证书路径：

-e DATABASE_SSL_CA='/certs/rds-combined-ca-bundle.pem'

在 docker run 中，使用 -v /local/certs:/certs:ro 将证书挂载到容器中，或者在 Kubernetes pod 规范中进行卷挂载。

对于启用身份验证的 Redis (ElastiCache, Azure Cache, Memorystore)：

-e REDIS_PASSWORD='REDIS_AUTH_TOKEN' \
-e REDIS_TLS='true'

对于 Redis Cluster 模式，请使用 REDIS_CLUSTER_NODES 替代 REDIS_HOST：

-e REDIS_CLUSTER_NODES='node1.cache.amazonaws.com:6379,node2.cache.amazonaws.com:6379'

当设置 REDIS_CLUSTER_NODES 时，REDIS_HOST 将被忽略。

如需包含所有环境变量的完整 docker run 命令，请参考 入门指南启动脚本或 生产环境部署清单。

验证

MySQL

mysql --host=DB_HOST --user=ai_service --password=<strong-password> \
  ai_service --port=3306 -e "SELECT 1"

预期结果：在单列中包含 1 的表格。

PostgreSQL

psql -h DB_HOST -U ai_service -d ai_service -c "SELECT 1"

预期结果：?column? 返回 1。

Redis

redis-cli -h REDIS_HOST ping

预期结果：PONG。

AI 服务迁移

启动 AI 服务后，检查日志是否存在启动错误：

docker logs ai-service 2>&1 | grep -i 'fatal\|error\|listening'

成功启动的日志显示 Server is listening on port 8000.。启动日志不会报告数据库驱动程序、架构或迁移计数，因此需要列出表来确认迁移是否已运行（见下文）。在新数据库中，迁移将创建 32 张表。

如果出现 schema "cs-on-premises" does not exist，请返回 PostgreSQL 架构前提条件部分。如果出现 unknown variable 'default-authentication-plugin'，请返回 MySQL 部分。

要列出由迁移创建的表：

PostgreSQL

SELECT table_name FROM information_schema.tables
 WHERE table_schema = 'cs-on-premises'
 ORDER BY table_name;

MySQL

SHOW TABLES IN ai_service;

应显示以 ai_assistant_、environments、security、insights、blob_storage 和 cs_migrations 为前缀的表。