first commit

2026-03-04 12:17:52 +08:00
commit ecb3e1d9b2
42 changed files with 4081 additions and 0 deletions
--- a/ORACLE_CONNECTION_GUIDE.md
+++ b/ORACLE_CONNECTION_GUIDE.md
@@ -0,0 +1,186 @@
+# Oracle数据库连接指南
+
+## Oracle连接角色说明
+
+### 什么是Oracle角色？
+
+Oracle数据库中的角色（Role）是一组权限的集合，用于简化用户权限管理。角色不是连接参数，而是数据库内部的权限管理机制。
+
+### 常见的Oracle角色
+
+1. **CONNECT** - 基本连接权限
+   - 允许用户连接到数据库
+   - 创建表、视图、序列等基本对象
+
+2. **RESOURCE** - 资源使用权限
+   - 允许用户创建存储过程、触发器等
+   - 使用表空间资源
+
+3. **DBA** - 数据库管理员权限
+   - 完全的数据库管理权限
+   - 可以管理所有数据库对象
+
+4. **SELECT_CATALOG_ROLE** - 数据字典查询权限
+   - 允许查询数据字典视图
+
+### 默认角色
+
+对于普通用户（如 `bizuser`），通常会被授予以下默认角色：
+- **CONNECT** - 基本连接权限
+- **RESOURCE** - 资源使用权限
+
+## Oracle连接参数说明
+
+### 基本连接参数
+
+- **主机地址 (host)**: Oracle数据库服务器的IP地址或主机名
+- **端口 (port)**: Oracle监听器端口，默认为1521
+- **服务名称 (service_name)**: Oracle数据库的服务名称，如ORCLPDB1
+- **用户名 (username)**: 数据库用户名
+- **密码 (password)**: 数据库密码
+
+### 高级连接参数
+
+- **mode**: 连接模式
+  - `SYSDBA`: 系统管理员模式
+  - `SYSOPER`: 系统操作员模式
+  - `NORMAL`: 普通用户模式（默认）
+
+- **threaded**: 线程模式
+  - `true`: 启用线程模式（推荐）
+  - `false`: 禁用线程模式
+
+## 连接字符串格式
+
+### 标准格式
+```
+oracle+oracledb://username:password@host:port/service_name
+```
+
+### 带参数格式
+```
+oracle+oracledb://username:password@host:port/service_name?encoding=UTF-8&nencoding=UTF-8&threaded=true
+```
+
+## 用户提供的连接信息
+
+根据您提供的Navicat连接信息：
+
+```
+主机地址: 192.168.13.27
+端口: 1521
+服务名称: ORCLPDB1
+用户名: bizuser
+密码: MySecurePass123
+角色: Default (CONNECT + RESOURCE)
+```
+
+## 连接测试
+
+### 使用测试脚本
+
+1. 启动API服务：
+   ```bash
+   python main.py
+   ```
+
+2. 运行Oracle连接测试：
+   ```bash
+   python test_oracle_connection.py
+   ```
+
+### 使用API接口
+
+```json
+{
+  "db_type": "oracle",
+  "host": "192.168.13.27",
+  "port": 1521,
+  "username": "bizuser",
+  "password": "MySecurePass123",
+  "database": "ORCLPDB1",
+  "threaded": true
+}
+```
+
+## 常见连接问题及解决方案
+
+### 1. TNS: 无法解析指定的连接标识符
+
+**原因**: 服务名称不正确或Oracle监听器未启动
+
+**解决方案**:
+- 检查服务名称是否正确
+- 确认Oracle监听器正在运行
+- 使用 `lsnrctl status` 检查监听器状态
+
+### 2. ORA-12541: TNS: 无监听程序
+
+**原因**: Oracle监听器未启动或端口被占用
+
+**解决方案**:
+- 启动Oracle监听器: `lsnrctl start`
+- 检查端口1521是否被占用
+- 确认防火墙设置
+
+### 3. ORA-01017: 用户名/口令无效
+
+**原因**: 用户名或密码错误
+
+**解决方案**:
+- 验证用户名和密码
+- 检查用户账户是否被锁定
+- 确认用户是否存在
+
+### 4. ORA-12514: TNS: 监听程序当前无法识别连接描述符中请求的服务
+
+**原因**: 服务名称不存在或未注册到监听器
+
+**解决方案**:
+- 检查服务名称是否正确
+- 使用 `lsnrctl services` 查看可用服务
+- 确认数据库实例正在运行
+
+## 连接池配置
+
+本项目为Oracle连接配置了专门的连接池参数：
+
+```python
+engine_kwargs = {
+    "pool_size": 10,        # 连接池大小
+    "max_overflow": 20,     # 最大溢出连接数
+    "pool_timeout": 30,     # 连接超时时间（秒）
+    "pool_recycle": 3600    # 连接回收时间（秒）
+}
+```
+
+## 环境变量配置
+
+可以通过环境变量配置Oracle连接参数：
+
+```bash
+# .env文件
+ORACLE_HOST=192.168.13.27
+ORACLE_PORT=1521
+ORACLE_USERNAME=bizuser
+ORACLE_PASSWORD=MySecurePass123
+ORACLE_SERVICE_NAME=ORCLPDB1
+```
+
+## 注意事项
+
+1. **角色不是连接参数**: Oracle角色是数据库内部的权限管理机制，不需要在连接字符串中指定
+2. **服务名称 vs SID**: 现代Oracle推荐使用服务名称而不是SID
+3. **字符编码**: 建议使用UTF-8编码以支持中文字符
+4. **连接安全**: 在生产环境中，建议使用SSL/TLS加密连接
+5. **连接池**: 使用连接池可以提高性能和资源利用率
+
+## 技术支持
+
+如果连接仍然失败，请检查：
+
+1. Oracle客户端库是否正确安装
+2. 网络连接是否正常
+3. Oracle数据库服务是否运行
+4. 防火墙和安全组设置
+5. 用户权限是否足够