aardio-erp实战排雷：3个核心问题的系统化解决指南

问题现象→程序启动失败提示缺少自定义库→本质原因：框架依赖未正确配置

问题定位

在Windows 10环境下启动aardio IDE并加载项目时，控制台出现"module not found: carl"错误提示，程序启动后立即退出。

根源解析

aardio-erp框架依赖自定义的carl组件库，该库未包含在aardio官方标准库中，需要手动部署到IDE的库目录。这就像盖房子时忘了装承重墙——框架核心组件缺失自然无法站立。

分步方案

🔧 Step 1：定位项目内的库文件
找到项目目录下的lib/carl/文件夹，这是框架的"核心引擎"所在。

🔧 Step 2：执行库文件迁移
将整个carl文件夹复制到aardio IDE的标准库目录（通常位于C:\Program Files\aardio\lib\）。
📌 注意：复制时保持原有文件夹结构，不要修改任何文件名——这就像移植植物要保留完整根系。

🔧 Step 3：验证部署结果
重新启动aardio IDE，创建新项目并尝试输入import carl。若未提示错误，则表示库文件部署成功。

预防建议

在项目根目录创建setup.bat文件，添加自动复制库文件的脚本：

@echo off
xcopy /E /Y lib\carl "C:\Program Files\aardio\lib\carl\"
echo 库文件已自动部署，请重启aardio IDE
pause

相似场景迁移
此方案适用于所有基于aardio开发的项目。当遇到module not found错误时，通常是自定义库未正确部署。可按相同步骤将项目专用库复制到aardio/lib/目录解决依赖问题。

问题现象→IIS环境下CGI请求无响应→本质原因：服务器映射配置错误

问题定位

在Windows Server 2019的IIS 10环境中，访问http://localhost/aardio-cgi时浏览器显示404错误，IIS日志中出现"Handler 'AardioCgiHandler' has a bad module 'FastCgiModule' in its module list"错误。

根源解析

IIS未正确配置FastCGI模块映射，导致无法将CGI请求路由到aardio-cgi/exe处理程序。这好比快递员拿着正确地址却找不到小区入口——路径正确但通道未打通。

分步方案

🔧 Step 1：检查IIS组件
打开"服务器管理器→添加角色和功能"，确认已安装"CGI"和"FastCGI"组件。

🔧 Step 2：配置模块映射
在IIS管理器中选择网站→处理程序映射→添加模块映射：

• 请求路径：*.cgi
• 模块：FastCgiModule
• 可执行文件：[项目路径]\aardio-cgi\exe
• 名称：AardioCgiHandler

🔧 Step 3：验证配置有效性
创建测试文件test.cgi，内容为print("Content-Type: text/html\n\nHello CGI")，通过浏览器访问该文件，若显示"Hello CGI"则配置成功。

预防建议

部署时使用IIS配置导出工具，将正确配置保存为web.config文件放在项目根目录，避免重复配置工作。

相似场景迁移
此方案适用于所有FastCGI应用部署（如PHP、Python CGI）。当遇到CGI请求404/500错误时，检查三点：处理程序映射是否存在、可执行文件路径是否正确、进程权限是否足够。

问题现象→客户端提示"数据库连接失败"→本质原因：配置文件参数不匹配

问题定位

客户端启动后停留在登录界面，点击"连接"按钮无反应，服务端日志显示"invalid connection string"错误。

根源解析

客户端与服务端的数据库配置参数不一致，主要涉及数据库类型（__drive）和连接线路（__appRoad）两个关键参数。这就像两个人用不同频率的对讲机——虽然都在说话但无法沟通。

分步方案

🔧 Step 1：检查服务端配置
打开服务端配置文件rpc/wwwroot/system/config.aardio，确认数据库连接字符串格式正确：

config.__drive = "mysql"  // 或 "mssql"
config.connStr = "server=127.0.0.1;database=erp;uid=root;pwd=123456"

🔧 Step 2：同步客户端配置
修改客户端配置文件lib/config.aardio，确保以下参数与服务端一致：

config.__drive = "mysql"  // 必须与服务端相同
config.__appRoad = "default"  // 线路标识需匹配

🔧 Step 3：验证数据库连接
在服务端执行rpc/wwwroot/system/sqlhelper.aardio测试脚本，若输出"连接成功"则表示服务端配置正确；客户端重新登录，若能显示用户列表则问题解决。

预防建议

创建配置同步工具，在服务端配置变更时自动更新所有客户端配置文件。可在res/version.txt中添加配置版本号，客户端启动时检查版本一致性。

相似场景迁移
此方案适用于所有C/S架构的数据库应用。当遇到连接问题时，应优先检查：①数据库服务是否运行 ②连接字符串格式 ③客户端与服务端配置一致性 ④网络端口是否开放。

总结与扩展

aardio-erp的这三个核心问题本质上都是"配置-部署-验证"链条中的环节缺失。记住开发三原则：依赖要显式（如库文件部署）、配置要同步（如数据库参数）、验证要及时（如测试脚本）。当遇到新问题时，可尝试通过lib/log.aardio查看详细日志，大部分问题都能在日志中找到线索。

开发就像解谜，每个错误提示都是通往成功的线索。保持耐心，善用工具，你就能让这个ERP框架顺畅运行起来！