AIGC标识 [小傅哥Agent编排项目]个人在学习中遇到的问题与解决方法

声明：此文章内容大多是在我实际遇到并解决问题后，由AI总结与生成解决方案的内容。本人承诺此文的内容属实，均由个人实践过具备可行性。由于实际配置、代码可能有所出入，因此此文仅提供解决思路与方向，不能完全照搬

【第一阶段】

  • 本地构建镜像时，需要打开 docker Desktop，否则报错：

  • 拉取镜像失败的解决方法：配置 docker desktop 的配置文件、且代理软件调至全局模式

    1

    {
    "dns": ["8.8.8.8", "8.8.4.4"],
    "registry-mirrors": [
        "https://docker.m.daocloud.io/",
        "https://huecker.io/",
        "https://dockerhub.timeweb.cloud",
        "https://noohub.ru/",
        "https://dockerproxy.com",
        "https://docker.mirrors.ustc.edu.cn",
        "https://docker.nju.edu.cn",
        "https://<your-aliyun-mirror>.mirror.aliyuncs.com/",
        "http://<your-daocloud-mirror>.m.daocloud.io",
        "https://registry.docker-cn.com",
        "http://hub-mirror.c.163.com"
    ],
    "runtimes": {
        "nvidia": {
            "path": "nvidia-container-runtime",
            "runtimeArgs": []
        }
    }
}

    image-20260221211321263

01. Maven 编译插件参数问题

  • 问题：maven-compiler-plugin 报 Parameter 'parameters' is unknown。
  • 解决：插件版本过低，改用 <compilerArgument>-parameters</compilerArgument> 传递参数，确保编译时保留方法参数名，解决 Spring MVC 参数解析异常。

02. PostgreSQL 密码反复失效

  • 问题：应用启动时频繁出现 password authentication failed for user "postgres"，即使重置密码后过段时间又失效。
  • 解决：
    • 为 vector_db 容器添加数据卷持久化（./pgvector/data:/var/lib/postgresql/data），防止容器重建导致密码重置。
    • 进入数据库容器 psql -U postgres，通过 ALTER USER postgres WITH PASSWORD '<db_password>'; 强制统一密码加密方式，并验证网络连接密码正确性。

03. Docker 构建网络问题

  • 问题：docker build 拉取基础镜像 openjdk:17-jdk-slim 超时或报错 502 Bad Gateway。
  • 解决：改用 docker pull eclipse-temurin:17-jdk

04. Docker Hub 镜像推送权限拒绝

  • 问题：docker push 报 denied: requested access to the resource is denied。
  • 解决：登录用户名 与镜像标签不一致，使用 docker tag 重新打标签

05. 容器启动报“no main manifest attribute”

  • 问题：应用容器日志显示 no main manifest attribute。
  • 解决：检查 dev-tech-app/pom.xml，发现 spring-boot-maven-plugin 中配置了 <skip>true</skip>，移除该配置后重新打包、构建镜像，容器正常启动。

06. 应用连接数据库密码认证失败（网络层面）

  • 问题：容器启动后仍报 password authentication failed，但数据库内密码正确。

  • 解决：

    • 通过 docker inspect 确认应用容器与数据库容器在同一网络（v10_my-network）。

    • 在 docker-compose-app-v1.0.yml 中通过环境变量覆盖数据库连接参数：

      environment:
  - SPRING_DATASOURCE_URL=jdbc:postgresql://vector_db:5432/ai-rag-knowledge
  - SPRING_DATASOURCE_USERNAME=postgres
  - SPRING_DATASOURCE_PASSWORD=<db_password>

    • 强制在数据库内重置密码并重启容器，最终连接成功。

07. Spring MVC 参数名解析失败

  • 问题：请求处理时报 Name for argument of type [java.lang.String] not specified。
  • 解决：在父 pom.xml 的 maven-compiler-plugin 中添加 <compilerArgument>-parameters</compilerArgument>，重新编译部署后解决。

08. Ollama 模型缺失

  • 问题：应用启动后报 model \"nomic-embed-text\" not found。
  • 解决：进入 ollama 容器执行 ollama pull nomic-embed-text 拉取所需嵌入模型。

09. 向量维度不匹配

  • 问题：上传文件时出现 ERROR: expected 1536 dimensions, not 768。
  • 解决：
    • 在 docker-compose-app-v1.0.yml 中添加环境变量 SPRING_AI_VECTORSTORE_PGVECTOR_DIMENSIONS=768，指定向量维度为 768（与 nomic-embed-text 模型匹配）。
    • 进入数据库删除旧表 DROP TABLE vector_store CASCADE;，让应用重启时自动重建正确维度的表。

10. Maven 编译插件参数缺失

  • 问题：maven-compiler-plugin 报 Parameter 'parameters' is unknown，导致 Spring MVC 无法解析方法参数名。
  • 解决：升级插件版本至 3.11.0，并在配置中添加 <compilerArgs><arg>-parameters</arg></compilerArgs>，确保编译时保留参数名。

11. PostgreSQL 密码反复失效

  • 问题：应用容器启动时频繁出现 password authentication failed for user "postgres"，即使重置密码后过段时间又失效。
  • 解决：
    • 为 vector_db 容器添加数据卷持久化（./pgvector/data:/var/lib/postgresql/data），防止容器重建导致数据丢失。
    • 进入数据库容器 psql -U postgres，强制重置密码：ALTER USER postgres WITH PASSWORD '<db_password>';。
    • 在应用容器中通过环境变量覆盖数据库连接配置，确保使用服务名 vector_db:5432。

12. Docker 构建网络问题（代理）

  • 问题：docker build 拉取基础镜像 openjdk:17-jdk-slim 超时或报 502 Bad Gateway。
  • 解决：
    • 配置 *** Verge 代理，切换为全局模式并关闭 TUN 模式。
    • 在 PowerShell 中设置 $env:HTTP_PROXY 和 $env:HTTPS_PROXY 强制 Docker 使用代理。注意要求 docker 使用的代理端口与 *** 中的端口保持一致
    • 改用 eclipse-temurin:17-jdk 成功构建。
  • 注意：
    • 完成后记得取消 docker 代理的使用

14. 容器启动报“no main manifest attribute”

  • 问题：应用容器日志显示 no main manifest attribute。

  • 解决：检查 dev-tech-app/pom.xml，发现 spring-boot-maven-plugin 中配置了 <skip>true</skip>，移除该配置后重新打包、构建镜像，容器正常启动。

  • 应用连接数据库密码认证失败（网络层面）

    • 问题：容器启动后仍报 password authentication failed，但数据库内密码正确。
    • 解决：
      • 通过 docker inspect 确认应用容器与数据库容器在同一网络。
      • 在 docker-compose-app-v1.0.yml 中通过环境变量覆盖数据库连接参数，使用服务名 vector_db:5432。
      • 强制在数据库内重置密码并重启容器，最终连接成功。

15. Spring MVC 参数名解析失败

  • 问题：请求处理时报 Name for argument of type [java.lang.String] not specified。
  • 解决：在父 pom.xml 的 maven-compiler-plugin 中添加 <compilerArgument>-parameters</compilerArgument>，重新编译部署后解决。

16. Ollama 模型缺失

  • 问题：应用启动后报 model \"nomic-embed-text\" not found，后续又报 deepseek-r1:1.5b 缺失。
  • 解决：进入 ollama 容器执行 ollama pull nomic-embed-text 和 ollama pull deepseek-r1:1.5b 拉取所需模型。

17. 向量维度不匹配

  • 问题：上传文件时出现 ERROR: expected 1536 dimensions, not 768。
  • 解决：
    • 在 docker-compose-app-v1.0.yml 中添加环境变量 SPRING_AI_VECTORSTORE_PGVECTOR_DIMENSIONS=768，指定向量维度为 768。
    • 进入数据库删除旧表 DROP TABLE vector_store CASCADE;，让应用重启时自动重建正确维度的表。

18. Ollama 返回 404/500（内存不足）

  • 问题：应用调用 Ollama 聊天接口时返回 404（模型未找到）或 500（内部错误），最终发现是服务器内存不足（1.6GB 可用，但 deepseek-r1:1.5b 需要 1.7GB）。
  • 解决：
    • 换用内存需求更小的模型，如 llama3.2:1b（约 0.6GB）。
    • 释放内存：停止非必需容器（redis-admin、nginx），限制 PostgreSQL 内存，设置 Ollama OLLAMA_KEEP_ALIVE=0 让模型空闲时立即卸载。
    • 增加 swap 空间（从 2GB 扩至 4GB）辅助内存不足问题。

19. 跨域请求失败（503 Service Unavailable）

  • 问题：前端请求返回 503，且 CORS 头缺失，状态码 (null)，实际是后端服务不可用（因 Ollama 内存不足导致应用超时）。
  • 解决：解决内存问题并换用小模型后，应用恢复正常，CORS 问题自然消失（若仍需配置，可在后端添加 @CrossOrigin 或全局 CORS 配置）。

20. DNS 无法解析 redis

  • 问题：应用日志显示 Unable to resolve 'redis'，Redisson 连接超时。
  • 解决：
    • 确认 redis 容器与 ai-rag-knowledge-app 在同一网络（v10_my-network）。
    • 重启应用容器以重新获取 DNS 配置：docker-compose -f docker-compose-app-v1.0.yml restart。
    • 若仍失败，重建应用容器或手动在 /etc/hosts 添加 redis 的 IP 作为临时方案。

21. HikariCP 线程饥饿警告

  • 问题：日志出现 Thread starvation or clock leap detected，提示线程调度延迟或时间跳变。
  • 解决：通常是由于系统负载过高或 CPU 资源紧张，可通过优化容器资源限制、增加 CPU/内存或排查高负载进程解决。

【第二阶段】

01. filesystem 配置错误

问题：Java 程序启动 MCP 的 filesystem 服务器时执行 npx 命令失败，抛出 CreateProcess error=2，提示系统找不到指定文件。原因是 Java 进程未继承系统的 PATH 环境变量，无法定位 npx。

解决方法：

  1. 在命令行中运行 where npx，得到 npx.cmd 的完整路径。
  2. 编辑 MCP 配置文件，将 filesystem 服务器的 command 修改为完整路径（注意转义反斜杠）。
  3. 重启 Java 应用程序，filesystem 服务器正常启动，报错消失。

02. npm 环境变量未展开导致路径错误

问题：npm 启动时加载配置，遇到 %USERPROFILE% 未被替换，导致访问不存在的路径（如 ...\%USERPROFILE%\npm-global）。

解决：检查并修改用户目录下的 .npmrc 文件，将其中包含 %USERPROFILE% 的配置项（如 prefix）替换为实际绝对路径（如 C:\Users\<用户名>\npm-global），并手动创建该目录。

03. openAi 的 base-url 配置错误

=== 错误 ===
    openai:
      base-url: https://apis.itedus.cn/v1/chat/completions
=== 正确 ===
    openai:
      base-url: https://apis.itedus.cn

04. Windows环境 MCPTest.java 测试类生成的txt文件部分内容乱码

项目 mcp-server-computer 的 ComputerService.java 中的同名方法全部替换成下面代码：

private String getWindowsSpecificInfo() {
    StringBuilder cache = new StringBuilder();
    try {
        // 用 ProcessBuilder 更稳一点
        Process process = new ProcessBuilder("cmd", "/c", "systeminfo")
                .redirectErrorStream(true)
                .start();

        // ✅ 指定 GBK 编码（简体中文 Windows 的 systeminfo 输出）
        try (java.io.BufferedReader reader = new java.io.BufferedReader(
                new java.io.InputStreamReader(process.getInputStream(), "GBK"))) {
            String line;
            while ((line = reader.readLine()) != null) {
                cache.append(line).append(System.lineSeparator());
            }
        }

        process.waitFor();
    } catch (Exception e) {
        e.printStackTrace();
    }
    return cache.toString();
}

05. 运行代码时，找不到 lombok 相关符号

问题总结

在 IntelliJ IDEA 中编译项目时，出现 Lombok 注解生成的 getter/setter 及 log 变量“找不到符号”的错误，尽管使用 Maven 命令行 (mvn clean compile) 能够成功编译。原因是 IDEA 默认使用自己的内部编译器（javac）进行构建，而该编译器未能正确集成 Lombok 的注解处理，导致无法识别 Lombok 生成的代码。

解决方式

通过强制 IDEA 将构建/运行操作委托给 Maven，让 IDEA 直接调用 Maven 的编译流程（与命令行一致），从而绕过内部编译器的问题。

关键步骤：

  1. 打开 File → Settings → Build, Execution, Deployment → Build Tools → Maven → Runner。
  2. 勾选 Delegate IDE build/run actions to Maven。
  3. 确保 Run actions using 选择 Maven。
  4. 在 Runner 区域，将 JRE 设置为与项目一致的 JDK 版本（如 JDK 17）。
  5. 点击 Apply 和 OK，重新编译即可。

此配置使 IDEA 的构建按钮（如 Build Project）实际执行 Maven 命令，从而正确触发 Lombok 的注解处理，解决了编译错误。

06. 连接mcp服务出现问题

image-20260303133040426

image-20260303133057249

07. 生成的博客内容乱码

解决方法：在 mcp 配置 json 文件中添加 "-Dfile.encoding=utf-8",

# 修改后：
{
  "mcpServers": {
    "mcp-server-csdn": {
      "command": "java",
      "args": [
        "-Dspring.ai.mcp.server.stdio=true",
        "-Dfile.encoding=utf-8",
        "-jar",
        "C:\\\\<项目路径>\\\\mcp\\\\jar\\\\mcp-server-csdn-1.0.0.jar",
        "--cnblog.api.cookie=<your_cookie>",
        "--cnblog.api.xsrfToken=<your_xsrfToken>"
      ]
    }
  }
}

08. 如何配置和上传镜像到阿里云

  • Dockerfile 无需直接运行，改正即可，在尾部添加 read -p "Press Enter to exit..."，可防止运行过快看不清日志就退出了
  • 运行 build.sh 和 push.sh：.\build.sh 和 .\push.sh

【第三阶段】

  • 记得在数据库里更改正确的配置，例如 API KEY

  • Ai Agent无法调用 http://127.0.0.1:4000/api/datasources：

    在 ai_client_tool_mcp 数据库配置中添加 --network host 参数

    image-20260515123132241

  • 访问不了云服务器：原因是nginx 的端口监听错误，应当监听 80，而非 3002

    1. 进入容器修改配置
      docker exec ai-agent-station-front-app sh -c "sed -i 's/listen 3002;/listen 80;/' /etc/nginx/conf.d/default.conf"
    2. 验证修改
      docker exec ai-agent-station-front-app cat /etc/nginx/conf.d/default.conf | grep listen
    3. 应该看到：
      listen 80;

  • 问题：agent 配置失败

    解决方法：所有加起来agent至多只能配置一个 Elasticsearch 的mcp工具

posted @ 2026-09-10 16:45  Zephyrix  阅读(6)  评论(0)    收藏  举报