diff --git a/src/main/java/net/lamgc/oracle/sentry/ApplicationMain.java b/src/main/java/net/lamgc/oracle/sentry/ApplicationMain.java index dd1748e..408a651 100644 --- a/src/main/java/net/lamgc/oracle/sentry/ApplicationMain.java +++ b/src/main/java/net/lamgc/oracle/sentry/ApplicationMain.java @@ -19,6 +19,10 @@ public class ApplicationMain { @SuppressWarnings("AlibabaConstantFieldShouldBeUpperCase") private final static Object mainThreadWaiter = new Object(); + /** + * 程序入口. + * @param args 程序参数. + */ public static void main(String[] args) { SpringApplication.run(ApplicationMain.class, args); diff --git a/src/main/java/net/lamgc/oracle/sentry/ComputeInstanceManager.java b/src/main/java/net/lamgc/oracle/sentry/ComputeInstanceManager.java index 2026bda..c6596b3 100644 --- a/src/main/java/net/lamgc/oracle/sentry/ComputeInstanceManager.java +++ b/src/main/java/net/lamgc/oracle/sentry/ComputeInstanceManager.java @@ -37,6 +37,10 @@ public class ComputeInstanceManager { sshIdentityProvider.loadAuthInfo(); } + /** + * 获取实例 SSH 认证配置提供器. + * @return 返回 SSH 认证配置提供器. + */ public SshAuthIdentityProvider getSshIdentityProvider() { return sshIdentityProvider; } diff --git a/src/main/java/net/lamgc/oracle/sentry/Constants.java b/src/main/java/net/lamgc/oracle/sentry/Constants.java index 3e89963..6053124 100644 --- a/src/main/java/net/lamgc/oracle/sentry/Constants.java +++ b/src/main/java/net/lamgc/oracle/sentry/Constants.java @@ -10,6 +10,9 @@ import org.springframework.stereotype.Component; @Component("sentry.constants") public final class Constants { + /** + * 本类唯一实例, 请不要进行设置. + */ public static Constants instance; private Constants() { @@ -21,6 +24,10 @@ public final class Constants { private String firstConnectionPolicy; + /** + * 获取 SSH 首次连接策略. + * @return 返回策略值. + */ @NonNull public String getFirstConnectionPolicy() { return firstConnectionPolicy; diff --git a/src/main/java/net/lamgc/oracle/sentry/OracleIdentityManager.java b/src/main/java/net/lamgc/oracle/sentry/OracleIdentityManager.java index 832a470..bb3c3e7 100644 --- a/src/main/java/net/lamgc/oracle/sentry/OracleIdentityManager.java +++ b/src/main/java/net/lamgc/oracle/sentry/OracleIdentityManager.java @@ -87,7 +87,9 @@ public final class OracleIdentityManager { /** * 通过配置文件加载身份信息. + *
加载成功后, 将会注册到身份管理器中. * @param identityConfig 身份信息文件. + * @return 返回已成功加载后, 配置文件对应的身份配置提供器. * @throws IOException 如果读取文件发生问题时将抛出该异常. */ public AuthenticationDetailsProvider loadFromConfigFile(File identityConfig) throws IOException { diff --git a/src/main/java/net/lamgc/oracle/sentry/common/InputStreamWrapper.java b/src/main/java/net/lamgc/oracle/sentry/common/InputStreamWrapper.java index c2c8af4..444ef5a 100644 --- a/src/main/java/net/lamgc/oracle/sentry/common/InputStreamWrapper.java +++ b/src/main/java/net/lamgc/oracle/sentry/common/InputStreamWrapper.java @@ -4,10 +4,20 @@ import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; +/** + * 输入流包装器. + *
准确来说只是屏蔽了 {@link InputStream#close()} 而已, + * 尝试修复 SSH 命令执行会话可能会关闭设置的输入流的问题. + * @author LamGC + */ public class InputStreamWrapper extends InputStream { private final InputStream source; - + + /** + * 包装一个输入流. + * @param source 输入源. + */ public InputStreamWrapper(InputStream source) { this.source = source; } diff --git a/src/main/java/net/lamgc/oracle/sentry/common/OutputStreamWrapper.java b/src/main/java/net/lamgc/oracle/sentry/common/OutputStreamWrapper.java index c41e56d..7ac87e7 100644 --- a/src/main/java/net/lamgc/oracle/sentry/common/OutputStreamWrapper.java +++ b/src/main/java/net/lamgc/oracle/sentry/common/OutputStreamWrapper.java @@ -3,10 +3,20 @@ package net.lamgc.oracle.sentry.common; import java.io.IOException; import java.io.OutputStream; +/** + * 输出流包装器. + *
准确来说只是屏蔽了 {@link OutputStream#close()} 而已, + * 尝试修复 SSH 命令执行会话可能会关闭设置的输出流的问题. + * @author LamGC + */ public class OutputStreamWrapper extends OutputStream { private final OutputStream target; - + + /** + * 包装一个输出流. + * @param target 目标输出流. + */ public OutputStreamWrapper(OutputStream target) { this.target = target; } diff --git a/src/main/java/net/lamgc/oracle/sentry/oci/compute/InstanceAction.java b/src/main/java/net/lamgc/oracle/sentry/oci/compute/InstanceAction.java index 26fc3ee..578e98d 100644 --- a/src/main/java/net/lamgc/oracle/sentry/oci/compute/InstanceAction.java +++ b/src/main/java/net/lamgc/oracle/sentry/oci/compute/InstanceAction.java @@ -1,5 +1,10 @@ package net.lamgc.oracle.sentry.oci.compute; +/** + * 实例动作. + *
可对实例执行的操作. + * @author LamGC + */ public enum InstanceAction { /** * 启动实例. @@ -30,6 +35,10 @@ public enum InstanceAction { this.actionValue = actionValue; } + /** + * 获取动作的 API 调用值. + * @return 返回 API 所规定的对应值. + */ public String getActionValue() { return actionValue; } diff --git a/src/main/java/net/lamgc/oracle/sentry/oci/compute/ssh/CommandExecSession.java b/src/main/java/net/lamgc/oracle/sentry/oci/compute/ssh/CommandExecSession.java index ffea763..1bed13d 100644 --- a/src/main/java/net/lamgc/oracle/sentry/oci/compute/ssh/CommandExecSession.java +++ b/src/main/java/net/lamgc/oracle/sentry/oci/compute/ssh/CommandExecSession.java @@ -71,6 +71,7 @@ public final class CommandExecSession implements Closeable { /** * 设置输入流. *
设置待执行命令的输入流. + * @param in 待设置的输入流。 */ public void setIn(InputStream in) { channelExec.setIn(new InputStreamWrapper(in)); @@ -79,6 +80,7 @@ public final class CommandExecSession implements Closeable { /** * 设置标准输出流. *
对应待执行命令的 Stdout. + * @param out 设置标准输出的输出流. */ public void setOut(OutputStream out) { channelExec.setOut(new OutputStreamWrapper(out)); @@ -87,6 +89,7 @@ public final class CommandExecSession implements Closeable { /** * 设置错误输出流. *
如果命令使用到, 错误信息会从该输出流输出. + * @param err 设置错误输出的输出流. */ public void setErr(OutputStream err) { channelExec.setErr(new OutputStreamWrapper(err)); diff --git a/src/main/java/net/lamgc/oracle/sentry/oci/compute/ssh/InstanceSsh.java b/src/main/java/net/lamgc/oracle/sentry/oci/compute/ssh/InstanceSsh.java index 59b8602..1523d7a 100644 --- a/src/main/java/net/lamgc/oracle/sentry/oci/compute/ssh/InstanceSsh.java +++ b/src/main/java/net/lamgc/oracle/sentry/oci/compute/ssh/InstanceSsh.java @@ -16,6 +16,12 @@ import java.util.Objects; import java.util.Set; import java.util.concurrent.TimeUnit; +/** + * 实例 SSH 客户端. + *
包装并简化了 SSH 会话的创建流程. + * @author LamGC + */ +@SuppressWarnings("unused") public class InstanceSsh implements AutoCloseable { private final static Logger log = LoggerFactory.getLogger(InstanceSsh.class); @@ -24,6 +30,11 @@ public class InstanceSsh implements AutoCloseable { private final SshAuthInfo authInfo; private final SshClient sshClient; + /** + * 创建连接实例用的 SSH 客户端. + * @param instance SSH 客户端对应的计算实例. + * @param authInfo SSH 认证配置. + */ public InstanceSsh(ComputeInstance instance, SshAuthInfo authInfo) { this.instance = Objects.requireNonNull(instance); this.authInfo = Objects.requireNonNull(authInfo); @@ -43,6 +54,12 @@ public class InstanceSsh implements AutoCloseable { sshClient.start(); } + /** + * 创建 SSH 会话. + *
允许创建多个 SSH 会话.
+ * @return 返回新的 SSH 会话.
+ * @throws IOException 会话创建失败时将抛出异常.
+ */
public SshSession createSession() throws IOException {
Set 注意: 该路径由 SSH 认证配置文件提供, 不保证私钥的存在.
+ * @return 返回私钥所在路径.
+ */
public File getPrivateKeyPath() {
return privateKeyPath;
}
+ /**
+ * 设置私钥路径.
+ * @param privateKeyPath 私钥路径.
+ */
public void setPrivateKeyPath(File privateKeyPath) {
this.privateKeyPath = privateKeyPath;
}
+ /**
+ * 获取私钥密码.
+ * @return 如果有, 返回非 {@code null} 值.
+ */
public String getKeyPassword() {
return keyPassword;
}
+ /**
+ * 设置私钥密码.
+ * 如果私钥存在密码但未提供密码, 将无法使用私钥验证会话.
+ * @param keyPassword 私钥密码.
+ */
public void setKeyPassword(String keyPassword) {
this.keyPassword = keyPassword;
}
diff --git a/src/main/java/net/lamgc/oracle/sentry/oci/compute/ssh/SshAuthIdentityProvider.java b/src/main/java/net/lamgc/oracle/sentry/oci/compute/ssh/SshAuthIdentityProvider.java
index 2cbe2c1..5431bd5 100644
--- a/src/main/java/net/lamgc/oracle/sentry/oci/compute/ssh/SshAuthIdentityProvider.java
+++ b/src/main/java/net/lamgc/oracle/sentry/oci/compute/ssh/SshAuthIdentityProvider.java
@@ -51,7 +51,11 @@ public final class SshAuthIdentityProvider {
.build());
private final AtomicBoolean needSave = new AtomicBoolean(false);
-
+ /**
+ * 创建 SSH 认证配置提供器.
+ * @param instanceManager 所属实例管理器.
+ * @param identityJson 认证配置文件对象.
+ */
public SshAuthIdentityProvider(ComputeInstanceManager instanceManager, File identityJson) {
this.instanceManager = instanceManager;
this.identityJsonFile = identityJson;
@@ -69,6 +73,11 @@ public final class SshAuthIdentityProvider {
}, 60, 10, TimeUnit.SECONDS);
}
+ /**
+ * 添加 SSH 认证配置.
+ * @param instanceId 配置对应的实例 Id.
+ * @param authInfo SSH 认证配置对象.
+ */
public void addSshAuthIdentity(String instanceId, SshAuthInfo authInfo) {
authInfoMap.put(instanceId, authInfo);
}
@@ -157,6 +166,7 @@ public final class SshAuthIdentityProvider {
/**
* 获取所有不存在 SSH 配置的实例 Id.
+ * @return 返回所有不存在对应 SSH 认证配置的实例 Id.
*/
private Set 用于认证服务器身份, 在首次登录成功后设置.
+ * @return 如果之前认证成功并保存过, 则不为 {@code null}, 否则需要进行首次连接确认.
+ */
public PublicKey getServerKey() {
return serverKey;
}
+ /**
+ * 设置服务器公钥.
+ * 如果本对象有关联的 {@link SshAuthIdentityProvider}, 则会通知 Provider 保存 SSH 认证配置文件.
+ * @param serverKey 服务器公钥.
+ */
public void setServerKey(PublicKey serverKey) {
this.serverKey = serverKey;
if (this.provider != null) {
@@ -44,14 +58,27 @@ public abstract class SshAuthInfo {
}
}
+ /**
+ * 设置 SSH 登录用户名.
+ * @param username 登录 SSH 的用户名.
+ */
public void setUsername(String username) {
this.username = username;
}
+ /**
+ * 设置 SSH 认证配置提供器.
+ * 设置后, 可在首次连接认证通过后, 保存服务器公钥到文件中.
+ * @param provider 所属提供器对象.
+ */
void setProvider(SshAuthIdentityProvider provider) {
this.provider = provider;
}
+ /**
+ * 认证类型.
+ * 如果没有所需认证类型, 就是没支持.
+ */
public enum AuthType {
/**
* 密码认证.
@@ -68,6 +95,10 @@ public abstract class SshAuthInfo {
this.targetClass = targetClass;
}
+ /**
+ * 获取类型所属的认证配置类.
+ * @return 返回认证配置类.
+ */
public Class extends SshAuthInfo> getTargetClass() {
return targetClass;
}
diff --git a/src/main/java/net/lamgc/oracle/sentry/oci/compute/ssh/SshAuthInfoSerializer.java b/src/main/java/net/lamgc/oracle/sentry/oci/compute/ssh/SshAuthInfoSerializer.java
index 52ad53d..14f59d5 100644
--- a/src/main/java/net/lamgc/oracle/sentry/oci/compute/ssh/SshAuthInfoSerializer.java
+++ b/src/main/java/net/lamgc/oracle/sentry/oci/compute/ssh/SshAuthInfoSerializer.java
@@ -23,6 +23,10 @@ import java.util.Collections;
*/
public final class SshAuthInfoSerializer implements JsonSerializer 序列化器支持多用.
+ */
public final static SshAuthInfoSerializer INSTANCE = new SshAuthInfoSerializer();
private SshAuthInfoSerializer() {}
diff --git a/src/main/java/net/lamgc/oracle/sentry/script/ScriptManager.java b/src/main/java/net/lamgc/oracle/sentry/script/ScriptManager.java
index 9bf81ff..c6fad75 100644
--- a/src/main/java/net/lamgc/oracle/sentry/script/ScriptManager.java
+++ b/src/main/java/net/lamgc/oracle/sentry/script/ScriptManager.java
@@ -23,6 +23,11 @@ public final class ScriptManager {
private final Map