C.1 使用前准备进入项目根目录cd D:\rag\rag-platform复制环境变量模板Copy-Item.env.example.envLinuxcp.env.example .env检查 Dockerdocker--versiondockercompose version当前docker-compose.yml编排的基础设施mysql - rag-mysql postgres - rag-postgres redis - rag-redis rabbitmq - rag-rabbitmq minio - rag-minio nacos - rag-nacos说明当前 Compose 主要编排基础设施。Java 微服务和前端是否容器化取决于后续是否补 Dockerfile 和完整服务编排。跨平台提醒Docker Compose 的 YAML 文件和 shell 脚本如果在 Windows 上编辑换行符默认为 CRLF。上传到 Linux 虚拟机后可能因为 CRLF 导致 YAML 解析错误或者脚本执行时报$\r: command not found建议在.gitattributes中配置*.sh text eollf *.yml text eollf如果已经出现 CRLF 问题可以在 Linux 上执行sed-is/\r$//*.sh *.yml也可以安装dos2unix工具批量处理。C.2 Docker Compose 常用命令启动全部依赖dockercompose --env-file .env up-d查看容器状态dockercomposeps查看全部日志dockercompose logs-f查看某个服务日志dockercompose logs-fmysqldockercompose logs-fpostgresdockercompose logs-fredisdockercompose logs-frabbitmqdockercompose logs-fminiodockercompose logs-fnacos停止全部容器dockercompose down重启某个服务dockercompose restart mysqldockercompose restart postgresdockercompose restart redisdockercompose restart rabbitmqdockercompose restart miniodockercompose restart nacos进入容器dockercomposeexecmysqlbashdockercomposeexecpostgresbashdockercomposeexecredisshdockercomposeexecrabbitmqbashdockercomposeexecminioshdockercomposeexecnacosbash查看数据卷dockervolumelsKnowHub 当前数据卷rag-mysql-data rag-postgres-data rag-redis-data rag-rabbitmq-data rag-minio-data rag-nacos-data rag-nacos-logs谨慎清理数据卷下面命令会删除容器和相关数据卷可能导致数据库、Redis、RabbitMQ、MinIO、Nacos 数据丢失。dockercompose down-v执行前必须确认已经备份数据。C.3 容器和端口速查组件容器名服务名默认端口MySQLrag-mysqlmysql3306PostgreSQL/pgvectorrag-postgrespostgres5432Redisrag-redisredis6379RabbitMQrag-rabbitmqrabbitmq5672RabbitMQ Managementrag-rabbitmqrabbitmq15672MinIO APIrag-miniominio9002MinIO Consolerag-miniominio9001Nacosrag-nacosnacos8848Nacos gRPCrag-nacosnacos9848Nacos Raftrag-nacosnacos9849Windows 端口检查Test-NetConnection127.0.0.1-Port 3306Test-NetConnection127.0.0.1-Port 5432Test-NetConnection127.0.0.1-Port 6379Test-NetConnection127.0.0.1-Port 5672Test-NetConnection127.0.0.1-Port 15672Test-NetConnection127.0.0.1-Port 9001Test-NetConnection127.0.0.1-Port 9002Test-NetConnection127.0.0.1-Port 8848Linux 端口检查ss-lntp|grep-E3306|5432|6379|5672|15672|9001|9002|8848一键全部端口检查docker compose up -d启动后等待约 30 秒让各容器完成初始化再执行下面的命令一次性确认全部端口已监听。Windows PowerShell$ports 3306,5432,6379,5672,15672,9001,9002,8848foreach($pin$ports){$resultTest-NetConnection127.0.0.1-Port$p-WarningAction SilentlyContinueWrite-Host端口$p:$($result.TcpTestSucceeded)}Linuxforportin330654326379567215672900190028848;doss-lntp|grep-q:$portecho端口$port: 监听中||echo端口$port: 未监听done如果有端口未监听单独查看该服务日志dockercompose logs-f服务名C.4 RabbitMQ 命令速查当前 Docker Compose 使用镜像rabbitmq:3.13-management默认端口5672 - 业务连接端口 15672 - 管理控制台默认环境变量RABBITMQ_DEFAULT_USER RABBITMQ_DEFAULT_PASS管理控制台地址http://localhost:15672如果部署在虚拟机地址改成http://虚拟机IP:15672查看 RabbitMQ 状态dockercomposeexecrabbitmq rabbitmqctl status查看用户dockercomposeexecrabbitmq rabbitmqctl list_users查看 vhostdockercomposeexecrabbitmq rabbitmqctl list_vhosts查看交换机dockercomposeexecrabbitmq rabbitmqctl list_exchanges查看队列dockercomposeexecrabbitmq rabbitmqctl list_queues带消息数量dockercomposeexecrabbitmq rabbitmqctl list_queues name messages_ready messages_unacknowledged consumers查看绑定关系dockercomposeexecrabbitmq rabbitmqctl list_bindings查看连接dockercomposeexecrabbitmq rabbitmqctl list_connections查看消费者dockercomposeexecrabbitmq rabbitmqctl list_consumers创建 vhost 示例dockercomposeexecrabbitmq rabbitmqctl add_vhost rag创建用户示例不要把真实密码写进教材或提交记录。下面只使用占位符。dockercomposeexecrabbitmq rabbitmqctl add_user rag_user replace-with-strong-password授权示例dockercomposeexecrabbitmq rabbitmqctl set_permissions-prag rag_user.*.*.*设置管理员标签dockercomposeexecrabbitmq rabbitmqctl set_user_tags rag_user administratorRabbitMQ 排查顺序1. docker compose ps 看 RabbitMQ 是否运行。 2. docker compose logs -f rabbitmq 看启动日志。 3. 访问 15672 管理台。 4. rabbitmqctl list_queues 看队列是否存在。 5. rabbitmqctl list_consumers 看消费者是否在线。 6. messages_ready 一直增长通常说明消费者没消费或消费失败。 7. messages_unacknowledged 一直增长通常说明消费者拿到消息但没有确认。说明RabbitMQ 的完整配置和代码实现参见第 9 章RabbitMQ 消息队列与索引任务和第 22 章全链路代码清单。学习阶段可以先在管理控制台确认 exchange、queue 和 binding 是否自动创建生产阶段需要补死信队列、消费幂等和告警。C.5 MinIO 命令速查当前 Docker Compose 使用镜像minio/minio:RELEASE.2024-07-16T23-46-41Z默认端口9002 - MinIO API 9001 - MinIO Console默认环境变量MINIO_ROOT_USER MINIO_ROOT_PASSWORDMinIO Console 地址http://localhost:9001MinIO API 地址http://localhost:9002如果部署在虚拟机http://虚拟机IP:9001 http://虚拟机IP:9002查看 MinIO 日志dockercompose logs-fminio使用 mc 客户端mcMinIO Client是 MinIO 官方命令行工具。如果本机尚未安装可以按系统选择一种方式。Windows 用户从 MinIO 官网下载mc.exe并放入PATH目录。macOSbrewinstallminio/stable/mcLinuxwgethttps://dl.min.io/client/mc/release/linux-amd64/mcchmodxmcsudomvmc/usr/local/bin/安装完成后执行mc--version确认mc可用后再配置 MinIO 别名。MinIO 常用命令行工具是mc。配置别名示例mcaliassetknowhub http://localhost:9002 ragminio replace-with-strong-password如果使用虚拟机mcaliassetknowhub http://虚拟机IP:9002 ragminio replace-with-strong-password查看 bucketmclsknowhub创建 bucketmcmb knowhub/rag-documents上传文件mccp./demo.md knowhub/rag-documents/demo.md下载文件mccpknowhub/rag-documents/demo.md ./demo-downloaded.md查看对象mclsknowhub/rag-documents递归查看mcls--recursiveknowhub/rag-documents删除对象mcrmknowhub/rag-documents/demo.md删除 bucket 前要确认里面没有重要文件。mcrb knowhub/rag-documentsMinIO 排查顺序1. docker compose ps 看 MinIO 是否运行。 2. docker compose logs -f minio 看启动日志。 3. 浏览器访问 9001 Console。 4. 确认 API 端口是 9002不是容器内部的 9000。 5. 确认 bucket 是否存在。 6. 确认账号密码是否和 .env 一致。 7. Java 服务如果运行在 WindowsMinIO 地址不要写容器内地址要写可访问的宿主机或虚拟机地址。说明MinIO 的完整配置和代码实现参见第 7 章文件服务、MinIO 与对象存储和第 22 章全链路代码清单。学习阶段可以先通过 Console 页面9001 端口手动查看上传的文件对象本地存储版本和 MinIO 版本的区别参见第 7 章 7.2 节。C.6 MySQL、PostgreSQL、Redis 快速命令虽然本附录标题重点是 Docker、RabbitMQ、MinIO但部署排查时经常也要快速进入数据库和 Redis。MySQL进入容器dockercomposeexecmysql mysql-uroot-p查看数据库SHOWDATABASES;USErag_demo;SHOWTABLES;PostgreSQL进入 psqldockercomposeexecpostgres psql-Upostgres-drag_vector检查 pgvectorSELECTextnameFROMpg_extensionWHEREextnamevector;查看向量表\d document_chunk_vectorRedis进入 redis-clidockercomposeexecredis redis-cli检查连接PINGPING是检查 Redis 连接是否正常的最快方法。返回PONG表示连接正常。如果连接失败优先检查 Redis 容器是否运行、端口是否正确、密码是否设置。dockercomposepsredis查看知识库 owner 缓存GET rag:kb:owner:{kbId}查看 keyKEYS rag:kb:owner:* KEYS rag:document:index-task:*说明生产环境不要频繁使用KEYS扫描大库学习和本地排查可以临时使用。NacosNacos 是服务注册中心和配置中心。检查 Nacos 运行状态最简单的方式是通过浏览器访问控制台。http://localhost:8848/nacos默认用户名和密码均为nacos登录后进入“服务管理 → 服务列表”预期看到四个服务rag-auth-service rag-gateway-service rag-knowledge-service rag-task-service并且健康实例数均为1。也可以使用 API 查询服务列表curl-XGEThttp://localhost:8848/nacos/v1/ns/service/list?pageNo1pageSize10-unacos:nacos如果服务列表为空说明微服务没有成功注册到 Nacos。优先检查各微服务的spring.cloud.nacos.discovery.server-addr同时确认 Nacos8848端口是否可达。C.7 高风险命令提醒以下命令可能删除数据或影响运行环境。删除容器和数据卷dockercompose down-v风险删除 MySQL、PostgreSQL、Redis、RabbitMQ、MinIO、Nacos 数据卷。删除单个 Docker volumedockervolumermrag-platform_rag-mysql-data风险删除对应组件数据。删除所有未使用资源dockersystem prune-a风险删除未使用镜像、容器、网络可能导致下次启动需要重新下载镜像。执行这些命令前先确认是否有数据备份 是否真的要重新初始化 是否会影响其他项目 是否是在正确项目目录中附录 C 的目标是让读者快速查命令。真正部署和交付流程仍以第 19 章为准。