AD.ps1 脚本使用文档

📋 概述

08年左右写了一版婀vbs版本的，目前只能支持到server2008版，现在不得不进行重构，老版本需要依赖dll文件，新的版本依赖powershell及ActiveDirectory模块。

AD.ps1 是一个用于批量管理 Active Directory 用户和组的生产环境优化脚本。该脚本支持创建、更新用户账户、组织单位、共享文件夹和权限设置，具备完全幂等性，可安全地重复执行。

🎯 主要特性

• 完全幂等性：可安全重复执行而不产生副作用
• 增量更新：支持增量和全量数据处理
• 数据保护：不会删除现有数据，只进行创建和更新
• 权限优化：避免不必要的权限移除和重新设置
• 健壮性：具备完善的错误处理和恢复机制
• 详细日志：完整的操作日志便于审计和故障排除

🔧 系统要求

• 操作系统：Windows Server 2022 或更高版本
• PowerShell：5.0 或更高版本
• 权限：管理员权限
• 模块依赖：ActiveDirectory 模块（RSAT 或 AD DS 角色）

📝 参数说明

必需参数

可选参数

🎮 运行模式详解

1. 标准模式

.\AD.ps1 -UsersJsonFile "user.json" -GroupsJsonFile "user_group.json"

适用场景：

• 开发和测试环境
• 首次使用脚本
• 需要手动确认操作

特点：

• 基本的AD用户和组管理功能
• 需要用户手动确认操作
• 标准日志输出

2. 生产模式（推荐）

.\AD.ps1 -UsersJsonFile "user.json" -GroupsJsonFile "user_group.json" -ProductionMode -Force

适用场景：

• 生产环境部署
• 定期数据同步
• 自动化脚本调用

特点：

• ✅ 完全幂等性操作
• ✅ 增量更新支持
• ✅ 数据保护机制
• ✅ 权限优化处理
• ✅ 安全操作保障

3. 调试模式

.\AD.ps1 -UsersJsonFile "user.json" -GroupsJsonFile "user_group.json" -DebugMode

适用场景：

• 问题排查
• 脚本调试
• 详细过程分析

特点：

• 显示详细的DEBUG级别日志
• 输出详细的操作过程信息
• 便于问题定位

4. 开发模式

.\AD.ps1 -UsersJsonFile "user.json" -GroupsJsonFile "user_group.json" -DevMode

适用场景：

• 脚本开发
• 逐步验证
• 学习脚本执行过程

特点：

• 每个操作后暂停，等待用户确认
• 显示详细的操作结果和返回值
• 错误时显示完整的错误详情

5. 完整日志模式

.\AD.ps1 -UsersJsonFile "user.json" -GroupsJsonFile "user_group.json" -ShowAllLogs

适用场景：

• 程序调用
• 日志分析
• 自动化监控

特点：

• 显示所有级别的日志到终端
• 终端输出与日志文件格式完全一致
• 便于程序解析

🔄 组合模式使用

生产环境最佳实践

# 完整的生产环境执行
.\AD.ps1 -UsersJsonFile "user.json" -GroupsJsonFile "user_group.json" -ProductionMode -Force -ShowAllLogs

开发调试组合

# 开发环境详细调试
.\AD.ps1 -UsersJsonFile "user.json" -GroupsJsonFile "user_group.json" -DevMode -DebugMode

增量更新

# 增量数据更新
.\AD.ps1 -UsersJsonFile "incremental_users.json" -GroupsJsonFile "incremental_groups.json" -ProductionMode -Force

自定义路径

# 自定义目录路径
.\AD.ps1 -UsersJsonFile "user.json" -GroupsJsonFile "user_group.json" -ShareRootDir "D:\Share" -HomeRootDir "D:\Home" -ProductionMode -Force

📊 JSON 文件格式

用户文件格式 (user.json)

[
  {
    "Name": "张三",
    "SamAccountName": "zhangsan",
    "UserPrincipalName": "zhangsan@domain.com",
    "Dept": "IT部;开发组",
    "Title": "软件工程师",
    "Email": "zhangsan@company.com",
    "Enabled": true
  }
]

组文件格式 (user_group.json)

[
  {
    "groupName": "IT部",
    "description": "信息技术部门",
    "members": ["zhangsan", "lisi"]
  }
]

📈 执行结果

脚本执行完成后会显示：

✓ 所有操作已成功完成!

=== 操作统计 ===
用户操作:
  - 创建用户: 5
  - 更新用户: 3
  - 状态变更: 2
  - 组关联添加: 8
  - 组关联移除: 1

✓ 生产模式执行完成
  - 所有操作均为幂等性安全操作
  - 可安全重复执行此脚本

详细日志请查看: .\ADSync.log

🚨 错误处理

退出代码

常见问题

问题1：PowerShell版本不兼容

错误: 此脚本需要PowerShell 5.0或更高版本
解决: 升级PowerShell到5.0+

问题2：缺少管理员权限

错误: 此脚本需要管理员权限运行
解决: 以管理员身份运行PowerShell

问题3：ActiveDirectory模块未安装

错误: ActiveDirectory模块未安装
解决: 安装RSAT或添加AD DS角色

🔒 安全注意事项

1. 权限管理：脚本需要管理员权限，请确保在安全环境中运行
2. 密码安全：默认密码应在首次登录后强制更改
3. 数据备份：执行前建议备份AD和文件系统
4. 测试验证：生产环境使用前请在测试环境充分验证
5. 日志审计：定期检查日志文件，监控异常操作

📚 最佳实践

生产环境部署

1. 使用生产模式：始终使用 -ProductionMode 参数
2. 启用强制模式：使用 -Force 避免交互式确认
3. 完整日志记录：使用 -ShowAllLogs 便于监控
4. 定期执行：设置定时任务进行增量同步

开发和测试

1. 逐步验证：使用 -DevMode 进行逐步验证
2. 详细调试：使用 -DebugMode 查看详细过程
3. 小批量测试：先用少量数据测试
4. 备份恢复：准备回滚方案

监控和维护

1. 日志监控：定期检查日志文件
2. 性能监控：关注执行时间和资源使用
3. 错误处理：建立错误通知机制
4. 版本管理：保持脚本版本更新

📞 技术支持

如遇到问题，请：

1. 查看详细日志文件
2. 使用调试模式重现问题
3. 收集错误信息和环境信息
4. 联系技术支持团队

版本: v6.0.0
最后更新: 2025年
维护: guilin chen