first commit

2026-03-04 12:17:52 +08:00
commit ecb3e1d9b2
42 changed files with 4081 additions and 0 deletions
--- a/ORACLE_OPTIMIZATION_GUIDE.md
+++ b/ORACLE_OPTIMIZATION_GUIDE.md
@@ -0,0 +1,238 @@
+# Oracle连接优化指南
+
+## 概述
+
+本文档详细说明了针对Oracle数据库连接失败问题的优化措施和解决方案。
+
+## 问题描述
+
+- **现象**: MySQL可以正常初始化，Oracle一直初始化失败，卡在连接失败
+- **原因**: Oracle连接参数配置不当，连接方式不符合oracledb库的最佳实践
+
+## 优化措施
+
+### 1. 数据库管理器优化 (`database_manager.py`)
+
+#### 1.1 连接URL构建优化
+
+**优化前**:
+```python
+# 使用复杂的Easy Connect字符串
+dsn = f"{host}:{port}/{service_name}"
+base_url = f"oracle+oracledb://{username}:{password}@{dsn}"
+```
+
+**优化后**:
+```python
+# 使用标准的SQLAlchemy URL格式
+base_url = f"oracle+oracledb://{username}:{password}@{host}:{port}/?service_name={service_name}"
+```
+
+#### 1.2 连接预测试机制
+
+添加了多种连接方式的预测试:
+- Easy Connect字符串
+- 分离参数连接
+- SID连接方式
+
+#### 1.3 连接池配置优化
+
+```python
+engine_kwargs = {
+    "pool_size": 5,
+    "max_overflow": 10,
+    "pool_timeout": 30,
+    "pool_recycle": 3600,
+    "pool_reset_on_return": "commit"
+}
+```
+
+### 2. 示例数据初始化优化 (`sample_data.py`)
+
+#### 2.1 增强日志记录
+
+```python
+logger.info(f"开始初始化Oracle示例数据，配置: host={config['host']}, port={config['port']}, service_name={config['service_name']}")
+```
+
+#### 2.2 连接参数传递
+
+```python
+conn_id = self.db_manager.create_connection(
+    db_type="oracle",
+    host=config["host"],
+    port=config["port"],
+    username=config["username"],
+    password=config["password"],
+    database=config["service_name"],
+    mode=config.get("mode"),
+    threaded=config.get("threaded", True)
+)
+```
+
+### 3. 测试工具
+
+#### 3.1 增强版连接测试 (`test_oracle_connection.py`)
+
+- 直接Oracle连接测试
+- 多种连接方式尝试
+- 详细的错误诊断
+- API连接测试
+
+#### 3.2 快速诊断工具 (`quick_oracle_test.py`)
+
+- 4种不同的连接方式测试
+- 常见错误代码分析
+- 解决方案建议
+
+## 连接方式说明
+
+### 方式1: Easy Connect字符串
+```python
+dsn = f"{host}:{port}/{service_name}"
+oracledb.connect(user=username, password=password, dsn=dsn)
+```
+
+### 方式2: 分离参数
+```python
+oracledb.connect(
+    user=username,
+    password=password,
+    host=host,
+    port=port,
+    service_name=service_name
+)
+```
+
+### 方式3: makedsn (Service Name)
+```python
+dsn = oracledb.makedsn(host, port, service_name=service_name)
+oracledb.connect(user=username, password=password, dsn=dsn)
+```
+
+### 方式4: makedsn (SID)
+```python
+dsn = oracledb.makedsn(host, port, sid=service_name)
+oracledb.connect(user=username, password=password, dsn=dsn)
+```
+
+## 常见错误及解决方案
+
+### ORA-12514: TNS:listener does not currently know of service requested
+
+**原因**: 服务名不存在或未注册到监听器
+
+**解决方案**:
+1. 检查服务名是否正确
+2. 确认服务已注册到监听器: `lsnrctl services`
+3. 尝试使用SID而不是服务名
+
+### ORA-12541: TNS:no listener
+
+**原因**: 监听器未运行
+
+**解决方案**:
+1. 启动监听器: `lsnrctl start`
+2. 检查监听器状态: `lsnrctl status`
+
+### ORA-01017: invalid username/password
+
+**原因**: 用户名或密码错误
+
+**解决方案**:
+1. 验证用户名和密码
+2. 检查用户是否存在且有连接权限
+
+### ORA-12170: TNS:Connect timeout occurred
+
+**原因**: 连接超时
+
+**解决方案**:
+1. 检查网络连接
+2. 检查防火墙设置
+3. 增加连接超时时间
+
+## 配置文件更新
+
+### config.py
+```python
+"oracle": {
+    "host": "192.168.1.100",
+    "port": 1521,
+    "username": "c##testuser",
+    "password": "123456",
+    "service_name": "XEPDB1"
+}
+```
+
+### .env.example
+```
+ORACLE_HOST=192.168.1.100
+ORACLE_PORT=1521
+ORACLE_USERNAME=c##testuser
+ORACLE_PASSWORD=123456
+ORACLE_SERVICE_NAME=XEPDB1
+```
+
+## 测试步骤
+
+### 1. 快速连接测试
+```bash
+python quick_oracle_test.py
+```
+
+### 2. 完整功能测试
+```bash
+python test_oracle_connection.py
+```
+
+### 3. 启动API服务测试
+```bash
+python main.py
+```
+
+## 最佳实践
+
+1. **使用标准的SQLAlchemy URL格式**，避免复杂的DSN构建
+2. **实施连接预测试**，在创建SQLAlchemy引擎前验证连接参数
+3. **配置适当的连接池参数**，提高连接性能和稳定性
+4. **添加详细的日志记录**，便于问题诊断
+5. **提供多种连接方式**，增加连接成功率
+6. **实施错误分析和建议**，帮助快速定位问题
+
+## 性能优化
+
+### 连接池配置
+- `pool_size`: 5 (基础连接数)
+- `max_overflow`: 10 (最大溢出连接数)
+- `pool_timeout`: 30秒 (获取连接超时)
+- `pool_recycle`: 3600秒 (连接回收时间)
+- `pool_reset_on_return`: "commit" (连接返回时重置)
+
+### SQLAlchemy配置
+- `echo`: False (不输出SQL语句)
+- `pool_pre_ping`: True (连接前ping测试)
+
+## 故障排除清单
+
+- [ ] Oracle数据库服务是否运行
+- [ ] 监听器是否启动 (`lsnrctl status`)
+- [ ] 服务名是否正确注册 (`lsnrctl services`)
+- [ ] 网络连接是否正常
+- [ ] 防火墙是否阻止连接
+- [ ] 用户名和密码是否正确
+- [ ] 用户是否有连接权限
+- [ ] oracledb库是否正确安装 (`pip install oracledb`)
+- [ ] 配置文件参数是否正确
+
+## 总结
+
+通过以上优化措施，Oracle连接的稳定性和成功率得到显著提升。主要改进包括:
+
+1. **简化连接URL构建**，使用标准格式
+2. **增加连接预测试**，提前发现问题
+3. **优化连接池配置**，提高性能
+4. **提供多种测试工具**，便于诊断
+5. **完善错误处理**，提供解决建议
+
+这些优化措施确保了Oracle数据库连接的可靠性，解决了初始化失败的问题。