20个Yearning新手必知问题：从安装到防御全解析

你还在为SQL注入防御工具的配置头疼吗？作为数据库管理员或开发人员，你是否遇到过审计流程混乱、权限管理复杂的问题？本文整理了Yearning用户最常遇到的20个问题，从安装部署到高级防御配置，一站式解决你的困惑。读完本文，你将能够独立完成Yearning的环境搭建、常见故障排查，并掌握核心功能的最佳实践。

一、安装部署常见问题

1. 手动安装时初始化数据库失败怎么办？

手动安装需确保已正确配置config.toml文件，初始化数据库命令为./Yearning install。若失败，检查MySQL服务是否正常运行，配置文件中的数据库连接信息是否正确。关键配置项包括：

[Mysql]
Db = "Yearning_go"
Host = "127.0.0.1"
Port = "3306"
Password = "xxxxxxx"
User = "root"

详细配置说明见conf.toml.template。

2. Docker部署时提示环境变量缺失如何解决？

Docker部署需确保所有必要环境变量已设置，包括SECRET_KEY、MYSQL_USER、MYSQL_ADDR等。完整的启动命令示例：

docker run -d -it -p8000:8000 -e SECRET_KEY=$SECRET_KEY -e MYSQL_USER=$MYSQL_USER -e MYSQL_ADDR=$MYSQL_ADDR -e MYSQL_PASSWORD=$MYSQL_PASSWORD -e MYSQL_DB=$Yearning_DB -e Y_LANG=zh_CN yeelabs/yearning

Docker部署详细指南见docker/README.md。

3. 启动Yearning后无法访问Web界面怎么办？

首先检查服务是否正常启动，可通过./Yearning run命令查看控制台输出。若提示端口被占用，需修改配置文件中的端口设置。默认Web端口为8000，确保防火墙已开放该端口。登录界面参考：

二、配置与初始化问题

4. SECRET_KEY的作用是什么？如何设置？

SECRET_KEY是用于token加密和数据库密码加密的盐值，必须包含16个字符。配置文件中设置：

[General]
SecretKey = "dbcjqheupqjsuwsm" # 必须16位字符

若忘记密钥，需重新生成并更新配置文件，否则可能导致加密数据无法解密。

5. 如何修改默认管理员密码？

初始管理员账号为admin，密码为Yearning_admin。登录后可在个人设置中修改密码，或通过Docker命令重置：

docker run --rm -it -e SECRET_KEY=$SECRET_KEY ... yeelabs/yearning "./Yearning reset_super"

用户管理模块实现见src/handler/manage/user/user.go。

6. 如何配置OIDC登录？

需在配置文件中启用OIDC并填写相关参数：

[Oidc]
Enable = true
ClientId = "yearning"
ClientSecret = "fefehelj23jlj22f3jfjdfd"
AuthUrl = "https://keycloak.xxx.ca/auth/realms/master/protocol/openid-connect/auth"
TokenUrl = "https://keycloak.xxx.ca/auth/realms/master/protocol/openid-connect/token"

OIDC登录实现代码见src/handler/login/oidcLogin.go。

三、功能使用问题

7. 如何创建第一个SQL审计工单？

登录系统后，在顶部导航栏选择"SQL审计"，点击"新建工单"，填写相关信息并提交。工单创建流程参考：。审计功能实现见src/handler/order/audit/audit.go。

8. AI助手功能如何启用和使用？

AI助手支持SQL优化建议和文本转SQL功能，需在配置中启用并设置相关参数。使用时在SQL编辑框点击"AI优化"按钮，即可获取优化建议。AI功能实现见src/handler/fetch/ai.go。文本转SQL界面参考：

9. 如何配置SQL检查规则？

系统内置多种SQL检查规则，管理员可在"系统设置-审计规则"中配置。规则包括语法检查、风险语句检测等。检查规则实现见src/handler/manage/settings/setting.go。

10. 如何查看历史查询记录？

在"查询记录"模块可查看所有用户的查询操作，包括执行时间、SQL语句、影响行数等。敏感字段会自动匿名化处理。查询记录界面参考：。记录功能实现见src/handler/order/record/record.go。

四、权限与用户管理

11. 如何创建新用户并分配角色？

管理员在"用户管理"模块创建用户，可选择预定义角色或自定义角色。系统支持RBAC权限模型，角色管理界面见src/handler/manage/roles/roles.go。角色包括管理员、审计员、普通用户等。

12. 如何限制用户只能访问特定数据库？

在"数据源管理"中为用户分配特定数据库权限，确保用户只能看到有权限的数据库。数据源管理实现见src/handler/manage/db/dbmanage.go。

13. OIDC登录配置失败怎么办？

检查OIDC配置中的AuthUrl、TokenUrl是否正确，确保RedirectUrL与OIDC服务端配置一致。OIDC登录实现代码见src/handler/login/oidcLogin.go。若提示证书错误，可尝试关闭SSL验证（生产环境不建议）。

五、高级功能与故障排查

14. 如何配置敏感字段匿名化？

在"系统设置-敏感字段"中添加需要匿名化的字段规则，支持正则表达式匹配。匿名化处理在查询审计时自动应用，确保敏感数据不会被未授权用户查看。实现代码见src/handler/query/query.go。

15. SQL审计工单审批流程如何自定义？

管理员可在"工作流设置"中配置多级审批流程，支持按项目、数据库类型等条件设置不同审批链。工作流实现见src/handler/manage/flow/flow.go。审计流程界面参考：

16. Yearning启动时报"数据库连接失败"如何解决？

检查MySQL服务是否正常运行，配置文件中的数据库地址和端口是否正确，网络是否通畅。可通过telnet mysql_host 3306测试连接。数据库模型定义见src/model/db.go。

17. 如何查看系统日志？

日志文件默认保存在项目根目录的logs文件夹中，日志级别可在配置文件中设置：

[General]
LogLevel = "debug"  # debug,info,warn,error

调试级别日志可帮助排查复杂问题，生产环境建议使用info级别。

六、日常使用与最佳实践

18. 如何批量导入SQL语句进行审计？

在"SQL审计"模块支持批量导入SQL文件，单次导入上限为1000行。建议大型SQL文件分批次导入，避免超时。SQL解析实现见src/handler/fetch/impl.go。

19. 如何定期备份Yearning数据？

Yearning数据存储在MySQL数据库中，建议定期备份Yearning_go数据库。可使用MySQL的mysqldump工具或通过Docker容器执行备份命令：

docker exec -it [container_id] mysqldump -u root -p$MYSQL_PASSWORD Yearning_go > backup.sql

20. 如何升级Yearning到最新版本？

Docker部署可通过拉取最新镜像并执行迁移命令升级：

docker run --rm -it -e ... yeelabs/yearning "./Yearning migrate"

手动升级需下载最新版本，替换可执行文件后运行./Yearning migrate完成数据库迁移。升级前建议备份数据。

总结与资源

本文覆盖了Yearning从安装到高级配置的20个常见问题，帮助新手快速上手。更多详细文档见官方文档，核心功能实现代码可参考src/handler/目录。使用过程中遇到问题，可通过项目Issue或邮件联系开发团队：[e-mail]。

系统仪表盘参考：，AI聊天功能参考：。

希望本文能帮助你更好地使用Yearning进行SQL审计和防御工作，欢迎在评论区分享你的使用经验！